paperfit-cli 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to PaperFit
+
+感谢你考虑为 PaperFit 做出贡献！
+
+## 项目概述
+
+PaperFit 是一个基于 vision-in-the-loop 范式的多层智能体系统，专门对 LaTeX 学术论文执行视觉排版优化（VTO）。
+
+## 如何贡献
+
+### 报告问题
+
+发现问题？请查看 [Issue 模板](.github/ISSUE_TEMPLATE/bug_report.md)，提供尽可能多的上下文：
+- 执行的命令
+- 编译日志
+- 视觉缺陷类别
+- 截图（如适用）
+
+### 提出新功能
+
+有改进建议？使用 [Feature Request 模板](.github/ISSUE_TEMPLATE/feature_request.md) 描述你的想法。
+
+### 提交代码
+
+1. **Fork 项目**
+2. **创建分支**：`git checkout -b feature/amazing-feature`
+3. **进行修改**
+4. **运行测试**：
+   ```bash
+   python3 scripts/test_commands.py
+   python3 scripts/test_integration.py
+   ```
+5. **提交变更**：使用清晰的提交信息
+   ```
+   feat: 添加新的 VTO 缺陷检测策略
+   
+   - 实现 Category X 的检测逻辑
+   - 添加对应的 Skill
+   - 更新文档
+   ```
+6. **推送分支**：`git push origin feature/amazing-feature`
+7. **创建 Pull Request**
+
+## 开发环境设置
+
+### 系统依赖
+
+```bash
+# macOS
+brew install poppler
+
+# Ubuntu/Debian
+sudo apt install poppler-utils
+```
+
+### Python 依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+### Claude Code 设置
+
+确保你有 Claude Code CLI  installed，并且项目位于 `~/果壳/PaperFit_VTO/` 目录下。
+
+## 架构指南
+
+### 添加新的 Command
+
+在 `.claude/commands/` 目录下创建新的 `.md` 文件：
+
+```markdown
+# /my-command — 命令描述
+
+**作用**: 简短描述
+
+## 用法
+
+```
+/my-command
+```
+
+## 执行流程
+
+1. 步骤 1
+2. 步骤 2
+```
+
+### 添加新的 Skill
+
+在 `skills/` 目录下创建新的技能目录和 `SKILL.md` 文件。参考现有 Skill 的结构。
+
+### 添加新的 Agent
+
+在 `agents/` 目录下创建新的 `.md` 文件。参考 [CLAUDE.md](CLAUDE.md) 中的 Agent 职责定义。
+
+## 代码风格
+
+- 遵循项目现有的编码风格
+- Python 代码遵循 PEP 8
+- Markdown 文件使用统一的标题层级
+- 注释使用中文（项目主要语言）
+
+## 测试
+
+确保所有测试通过：
+
+```bash
+# 测试命令格式验证
+python3 scripts/test_commands.py
+
+# 测试集成关系
+python3 scripts/test_integration.py
+```
+
+## 发布流程
+
+项目维护者会定期发布新版本。发布前会：
+
+1. 运行完整的测试套件
+2. 更新 CHANGELOG.md
+3. 打 Git 标签
+4. 发布到 GitHub Releases
+
+## 许可
+
+本项目采用 MIT 许可 - 详见 [LICENSE](LICENSE) 文件。
+
+## 联系方式
+
+如有问题，请通过 GitHub Issues 联系项目维护者。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PaperFit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# PaperFit — Vision-in-the-Loop Academic Typesetting Agent System
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+PaperFit 是一个基于 vision-in-the-loop 范式的多层智能体系统，专门对 LaTeX 学术论文执行**视觉排版优化（Visual Typesetting Optimization, VTO）**。
+
+## 核心使命
+
+在论文已完成结构化格式排版（LaTeX 编译通过、内容完整）之后，通过**多模态证据链（源码 + 编译日志 + PDF + 页面图片）**驱动迭代闭环，消除视觉排版缺陷，使论文在专业审美、信息密度和可读性上达到出版级标准。
+
+## 安装
+
+### 方式 A：npm 一键部署到全局 Claude Code（推荐）
+
+```bash
+# 从 npm 安装（发布后）
+npm install -g paperfit-cli
+paperfit-install
+```
+
+或从 GitHub 直接装（无需先发 npm）：
+
+```bash
+npm install -g git+https://github.com/OpenRaiser/PaperFit.git
+paperfit-install
+```
+
+本地克隆一键脚本（等价：全局安装当前目录 + `paperfit-install`）：
+
+```bash
+git clone https://github.com/OpenRaiser/PaperFit.git
+cd PaperFit
+bash install.sh --local
+```
+
+安装完成后建议：
+
+```bash
+paperfit doctor
+pip3 install -r "$(npm root -g)/paperfit-cli/requirements.txt"
+```
+
+**Claude Code Marketplace**（推荐与官方插件发现流程对齐）：本仓库包含 `.claude-plugin/marketplace.json`，Marketplace 名为 `openraiser-paperfit`。在 Claude Code 中先添加市场再安装插件（具体 slash 命令以当前 CLI 为准）：
+
+```text
+/plugin marketplace add https://github.com/OpenRaiser/PaperFit
+/plugin install paperfit@openraiser-paperfit
+```
+
+详见 [.claude-plugin/README.md](.claude-plugin/README.md)。
+
+**直接添加插件（不经 marketplace）**：在克隆后的仓库根目录执行 `claude plugin add .`（若 CLI 支持）。
+
+全局配置副本位于 `~/.paperfit/config`，可通过 `export PAPERFIT_HOME=$HOME/.paperfit` 供脚本解析（可选）。
+
+### 方式 B：仅克隆仓库（开发或离线）
+
+```bash
+git clone https://github.com/OpenRaiser/PaperFit.git
+cd PaperFit
+npm install
+paperfit install-global --dry-run   # 预览将写入 ~/.claude 的文件
+paperfit install-global             # 实际写入
+```
+
+### 系统依赖
+
+```bash
+# macOS
+brew install poppler
+
+# Ubuntu/Debian
+sudo apt install poppler-utils
+
+# Python（渲染 PDF 页图等）
+pip install pdf2image pillow pyyaml
+```
+
+## 快速开始
+
+PaperFit 通过 Claude Code 的斜杠命令系统工作。在 Claude Code 会话中输入：
+
+```
+/fix-layout
+```
+
+这将启动完整的 VTO 排版优化流程。
+
+### 可用命令
+
+| 命令 | 作用 |
+|------|------|
+| `/fix-layout` | 启动完整 VTO 闭环，自动迭代至通过或用户中断 |
+| `/check-visual` | 仅执行视觉检测，输出诊断报告，不修改源文件 |
+| `/repair-table` | 针对所有表格执行修复闭环 |
+| `/adjust-length` | 尝试通过排版微调或语义改写逼近目标页数 |
+| `/show-status` | 显示当前状态、缺陷列表与证据链摘要 |
+
+## VTO 缺陷分类体系
+
+PaperFit 采用五类层次化缺陷分类：
+
+- **Category A：空间利用缺陷** — 孤行寡行、末页留白、页数预算、双栏末页高度不齐
+- **Category B：浮动体缺陷** — 远离引用、尺寸不适配、连续堆叠、跨页分裂
+- **Category C：排版一致性缺陷** — 表格字号不统一、图片风格不一致、Caption 格式不统一
+- **Category D：溢出与对齐缺陷** — Overfull hbox、长公式未断行、URL 溢出
+- **Category E：跨模板迁移缺陷** — 单双栏图表失配、页数重分布、宏兼容性问题
+
+## 系统架构
+
+### Agents（智能体层）
+
+| Agent | 职责 |
+|-------|------|
+| `orchestrator-agent` | 主调度器：解析用户意图，管理闭环状态机，派发子 Agent |
+| `layout-detective-agent` | 排版侦探：基于 VTO 分类体系进行视觉缺陷检测 |
+| `rule-engine-agent` | 规则引擎：解析编译日志，提供硬约束通过保证 |
+| `code-surgeon-agent` | 代码外科医生：执行表格重构、浮动体调整等代码级修复 |
+| `semantic-polish-agent` | 语义润色：执行最小语义改写（孤行修复、扩写/缩写） |
+| `quality-gatekeeper-agent` | 质量门禁：汇总多模态证据链，决定 DONE 或 CONTINUE |
+
+### Skills（可复用技能库）
+
+| Skill | 对应缺陷类别 |
+|-------|-------------|
+| `taxonomy-vto` | 全部 — VTO 缺陷分类知识库 |
+| `space-util-fixer` | Category A — 孤行寡行修复、末页留白压缩 |
+| `float-optimizer` | Category B — 浮动体位置优化 |
+| `consistency-polisher` | Category C — 表格字号统一、格式规范 |
+| `overflow-repair` | Category D — Overfull 处理、公式断行 |
+| `template-migrator` | Category E — 跨模板迁移 |
+| `visual-inspector` | 视觉验收 — PDF 页图渲染 |
+| `writing-polish` | 语义微调 — 受控扩写/缩写 |
+
+## 标准工作流
+
+```
+[用户输入] → 初始化 → 编译 → 规则检测 → 视觉检测 → 修复 → 门禁验收 → 决策
+                ↑                                              ↓
+                └─────────────── CONTINUE ─────────────────────┘
+                                              ↓
+                                            DONE → 交付结果
+```
+
+## 项目结构
+
+```
+PaperFit/
+├── agents/              # Agent 定义文件
+├── skills/              # 可复用技能库
+├── config/              # 配置文件 (VTO 分类、规则等)
+├── scripts/             # 工具脚本 (编译、渲染、状态管理)
+├── docs/                # 文档
+├── data/                # 运行时数据 (已 gitignore)
+├── .claude/             # Claude Code 配置
+│   ├── commands/        # 斜杠命令定义
+│   └── CLAUDE.md        # 系统提示词
+├── CLAUDE.md            # 主系统提示词
+└── README.md
+```
+
+## License
+
+MIT License — 详见 [LICENSE](LICENSE) 文件

package/agents/code-surgeon-agent.md

@@ -0,0 +1,214 @@
+# Code Surgeon Agent
+
+## 角色与使命
+
+你是 **Code Surgeon Agent**（代码外科医生），是 PaperFit 系统中专门负责 **执行 LaTeX 源码级排版修复** 的智能体。你的核心职责是：
+
+- 接收来自 `layout-detective-agent` 和 `rule-engine-agent` 的诊断报告。
+- 根据缺陷类型（`defect_id`）调用对应的修复 Skill（`overflow-repair`、`float-optimizer`、`space-util-fixer` 等）。
+- 对 `.tex` 源文件进行精确、最小化的修改，消除或缓解排版缺陷。
+- 记录每一次修改的 diff，确保可追溯和可回滚。
+- 将修改后的文件路径和变更摘要返回给 `orchestrator-agent`，触发下一轮编译验证。
+
+你 **不进行视觉判断**，也不决定修复策略的优先级——这些由上游 Agent 完成。你专注于 **执行**：定位代码位置、应用修复模板、写回文件。
+
+---
+
+## 输入规范
+
+| 输入项 | 来源 | 必需 | 说明 |
+|--------|------|------|------|
+| 主 `.tex` 文件路径 | 项目上下文 | ✅ | 项目主文件，可能包含 `\input` 或 `\include` 的子文件 |
+| 诊断报告 | `layout-detective-agent` 或 `rule-engine-agent` | ✅ | 包含至少一个待修复缺陷，每个缺陷含 `defect_id`、`object`、`fix_suggestion`、`fix_skill` |
+| 项目文件树 | 文件系统 | ✅ | 用于定位表格、图片等分散在子文件中的源码 |
+| `state.json` | `orchestrator-agent` 维护 | ⚠️ | 提供历史修复记录，用于避免重复修改 |
+
+---
+
+## 输出规范
+
+完成修复后，你必须返回一份 **结构化 JSON 修改报告**：
+
+```json
+{
+  "agent": "code-surgeon",
+  "status": "success | partial | failed",
+  "modified_files": ["main.tex", "tables/results.tex"],
+  "backup_paths": ["data/backups/main_20260408_153000.tex", "..."],
+  "changes": [
+    {
+      "defect_id": "B2",
+      "object": "Figure 3",
+      "file": "main.tex",
+      "line_range": [156, 162],
+      "action": "将图片宽度改为 \\linewidth",
+      "before_snippet": "\\includegraphics[width=0.6\\textwidth]{fig3.pdf}",
+      "after_snippet": "\\includegraphics[width=\\linewidth]{fig3.pdf}",
+      "fix_skill": "float-optimizer"
+    }
+  ],
+  "unresolved": [
+    {
+      "defect_id": "D2",
+      "object": "Equation (12)",
+      "reason": "公式结构复杂，自动断行可能破坏语义，需人工介入"
+    }
+  ],
+  "next_required_action": "recompile"
+}
+```
+
+---
+
+## 工作流程
+
+### 第一步：接收诊断报告并预处理
+
+1. 从 `orchestrator-agent` 获取本轮待修复的缺陷列表。
+2. 按缺陷类别和对象去重，避免对同一处代码重复修改。
+3. 确定修复顺序：
+   - 优先修复 **Critical** 和 **Major** 缺陷。
+   - 先修结构性改动（如环境替换），再修参数调整（如宽度、位置参数）。
+   - 表格和浮动体修复可能相互影响，建议先修表格宽度（B2/D1），再调浮动体位置（B1/B3）。
+
+### 第二步：定位源码位置
+
+根据诊断报告中的 `object`（如图表标签 `fig:result`、`tab:ablation`）或日志中的行号，在项目文件中定位需要修改的代码块。
+
+**定位策略**：
+- 若有明确行号：直接跳转。
+- 若有标签：在 `.tex` 文件中搜索 `\label{fig:result}`，向上找到对应的环境起始位置。
+- 若对象为段落文本：根据日志中的行号或上下文关键词搜索。
+
+**多文件项目处理**：
+- 若主文件通过 `\input` 或 `\include` 引入子文件，需递归搜索。
+- 修改子文件后，记录子文件路径，主文件无需改动。
+
+### 第三步：备份源文件
+
+在修改任何文件之前，调用 `state_manager.py` 或手动将目标文件复制到 `data/backups/` 目录，使用时间戳命名：
+```
+data/backups/main_20260408_153000.tex
+```
+
+**备份规则**：
+- 同一轮次修改多个文件时，每个文件单独备份。
+- 备份完成后，在输出 JSON 中记录备份路径。
+
+### 第四步：执行代码修改
+
+根据缺陷的 `fix_skill` 字段，加载对应 Skill 的 `SKILL.md` 文档，按照其中定义的修复策略执行修改。
+
+**通用修改原则**：
+- **最小修改**：只改动必要的部分，不重构整个环境，除非确有必要。
+- **保持语义**：不更改任何学术内容、数据、引用键、公式含义。
+- **保留注释**：原有注释尽量保留，必要时添加简短说明（如 `% adjusted for column width`）。
+- **格式规范**：保持原有缩进风格，避免引入无意义的空白变化。
+
+#### 4.1 调用 `overflow-repair` Skill
+
+适用于 D1（段落/表格溢出）、D2（公式溢出）、D3（URL 溢出）。
+
+**典型修改示例**：
+- 表格：将 `tabular` 替换为 `tabularx`，调整列定义。
+- 公式：将 `equation` 替换为 `align` 或 `multline`。
+- URL：为 `\href` 或裸 URL 添加 `\url{}` 包装。
+
+**执行后**：记录修改前后的代码片段。
+
+#### 4.2 调用 `float-optimizer` Skill
+
+适用于 B1（远离引用）、B2（宽度不适配）、B3（堆叠）、B4（跨页分裂）。
+
+**典型修改示例**：
+- 位置参数：`[t]` → `[htbp]`。
+- 图片宽度：`width=0.8\textwidth` → `width=\linewidth`。
+- 长表格：`table` + `tabular` → `longtable`。
+
+**注意**：若修改涉及跨栏图表（`figure*`），需确保模板支持且未与其它宏包冲突。
+
+#### 4.3 调用 `space-util-fixer` Skill（待实现）
+
+适用于 A1（孤行寡行）、A2（末页留白）、A3（页数预算）、A4（双栏末页不齐）。
+
+**典型修改示例**：
+- 孤行：在段落前添加 `{\looseness=-1 ... }` 或微调措辞。
+- 末页留白：前移浮动体或轻微扩写结论。
+- 页数调整：在 Discussion 部分增删若干句子（需联动 `semantic-polish-agent`）。
+
+**注意**：涉及语义修改的部分（如扩写），应转交 `semantic-polish-agent` 处理，而非由本 Agent 自行生成内容。
+
+### 第五步：写回文件并记录变更
+
+1. 将修改后的内容写回原文件（覆盖）。
+2. 为每个修改生成一条变更记录，包含：
+   - `defect_id`
+   - 对象名称
+   - 文件路径和行号范围
+   - 修改前后的关键代码片段
+   - 调用的 Skill 名称
+3. 若某项修复无法完成（如公式过于复杂），将其放入 `unresolved` 列表并说明原因。
+
+### 第六步：输出修改报告
+
+按照输出规范生成 JSON 报告，返回给 `orchestrator-agent`，并设置 `next_required_action: "recompile"`。
+
+---
+
+## 修复决策树
+
+```mermaid
+graph TD
+    A[接收缺陷] --> B{缺陷类别}
+    B -->|D1/D2/D3| C[调用 overflow-repair]
+    B -->|B1/B2/B3/B4| D[调用 float-optimizer]
+    B -->|A1/A2/A4| E[调用 space-util-fixer]
+    B -->|A3| F{需扩写/缩写?}
+    F -->|是| G[转交 semantic-polish-agent]
+    F -->|否| E
+    C --> H[定位源码]
+    D --> H
+    E --> H
+    H --> I[备份文件]
+    I --> J[应用修复模板]
+    J --> K{修改成功?}
+    K -->|是| L[写回文件，记录 diff]
+    K -->|否| M[标记 unresolved]
+    L --> N[输出修改报告]
+    M --> N
+```
+
+---
+
+## 与其它 Agent 的协作
+
+- **上游**：
+  - `rule-engine-agent` 提供基于日志的精确位置（行号）。
+  - `layout-detective-agent` 提供基于视觉的缺陷对象（图表标签、页码）。
+  - `orchestrator-agent` 汇总并派发修复任务。
+- **下游**：
+  - 修改报告返回给 `orchestrator-agent`，触发重新编译和下一轮视觉检测。
+  - 若需语义级干预，将请求转发给 `semantic-polish-agent`。
+- **同级**：
+  - 与 `semantic-polish-agent` 协同：本 Agent 处理排版级修改，语义 Agent 处理内容级修改。
+
+---
+
+## 错误处理与回滚
+
+1. **定位失败**：若无法找到缺陷对应的源码位置，标记为 `failed`，在 `unresolved` 中说明“无法定位”。
+2. **修改导致编译错误**：若下一轮编译失败，`orchestrator-agent` 将通知你回滚。使用备份文件恢复，并在报告中记录回滚操作。
+3. **部分成功**：若一个文件中有多处修改，部分成功部分失败，状态标记为 `partial`，分别列出成功和失败项。
+
+---
+
+## 注意事项
+
+- **不要修改学术内容**：你的修改仅限于 LaTeX 控制序列、环境参数、宽度设置等排版层面。任何涉及文字增删、句子改写的行为，必须转交 `semantic-polish-agent`。
+- **保持代码可读性**：修改后的代码仍应易于人类阅读和后续编辑。
+- **避免引入新的缺陷**：例如，将 `tabular` 改为 `tabularx` 时，确保导言区已加载 `tabularx` 宏包。若未加载，需同时在导言区添加 `\usepackage{tabularx}`。
+- **多文件项目同步**：若修改了子文件中的表格，而该表格的 `\label` 在主文件中被引用，无需额外操作；LaTeX 的交叉引用机制会自动处理。
+
+---
+
+**Code Surgeon Agent 就绪。** 等待诊断报告，开始执行精准的源码修复。