paperfit-cli 1.0.0

package/scripts/float_fixers.py

@@ -0,0 +1,861 @@
+#!/usr/bin/env python3
+"""
+Float Fixers Module
+
+处理 Category B：浮动体缺陷
+- B1: 浮动体远离首次引用
+- B2: 浮动体大小不适配栏宽
+- B3: 浮动体连续堆叠
+- B4: 浮动体跨页分裂
+
+该模块被 code-surgeon-agent 调用，执行对 .tex 源码的精确修改。
+所有修复遵循最小修改原则，不改变学术内容。
+"""
+
+import re
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional, Tuple, Any
+
+
+# ============================================================
+# 数据结构定义
+# ============================================================
+
+@dataclass
+class FixResult:
+    """修复结果"""
+    defect_id: str
+    object_name: str
+    action: str
+    before: str
+    after: str
+    page: int = 0
+    line_number: Optional[int] = None
+    success: bool = False
+
+
+@dataclass
+class FloatFixReport:
+    """修复报告"""
+    status: str  # success | partial | failed
+    modified_files: List[str] = field(default_factory=list)
+    changes: List[FixResult] = field(default_factory=list)
+    unresolved: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "skill": "float-optimizer",
+            "status": self.status,
+            "modified_files": self.modified_files,
+            "changes": [
+                {
+                    "defect_id": c.defect_id,
+                    "object": c.object_name,
+                    "action": c.action,
+                    "before": c.before,
+                    "after": c.after,
+                    "page": c.page,
+                    "line_number": c.line_number,
+                    "success": c.success,
+                }
+                for c in self.changes
+            ],
+            "unresolved": self.unresolved,
+        }
+
+
+# ============================================================
+# B1：浮动体远离首次引用
+# ============================================================
+
+def fix_float_reference_distance(
+    tex_content: str,
+    float_label: str,
+    ref_page: int,
+    float_page: int,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复浮动体远离首次引用问题
+
+    策略优先级:
+    1. 调整位置参数为 [htbp]
+    2. 在引用点后添加 \FloatBarrier
+    3. 移动浮动体源码位置
+    4. 拆分大型浮动体
+
+    Args:
+        tex_content: .tex 文件内容
+        float_label: 浮动体标签 (如 "fig:result" 或 "tab:results")
+        ref_page: 首次引用所在页码
+        float_page: 浮动体实际所在页码
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    # 计算距离
+    distance = abs(float_page - ref_page)
+    if distance <= 1:
+        # 距离在可接受范围内
+        return tex_content, None
+
+    # 定位浮动体环境
+    float_type = "figure" if "fig" in float_label.lower() else "table"
+
+    # 策略 1: 调整位置参数
+    pattern = r'\\begin\{' + float_type + r'\}(\[[^\]]*\])?'
+    matches = list(re.finditer(pattern, tex_content))
+
+    # 找到包含目标 label 的浮动体
+    target_match = None
+    for match in matches:
+        # 向后查找 \label
+        after_start = match.end()
+        label_pattern = r'\\label\{' + re.escape(float_label) + r'\}'
+        label_match = re.search(label_pattern, tex_content[after_start:after_start + 500])
+        if label_match:
+            target_match = match
+            break
+
+    if target_match:
+        pos_param = target_match.group(1) if target_match.group(1) else ""
+
+        # 检查当前参数是否限制性强
+        if pos_param in ['[t]', '[b]', '[h]', '[!t]', '[!b]', '[!h]']:
+            # 改为 [htbp]
+            new_param = "[htbp]"
+            modified_content = tex_content[:target_match.start(1)] + new_param + tex_content[target_match.end(1):]
+            return modified_content, FixResult(
+                defect_id="B1",
+                object_name=float_label,
+                action=f"将浮动体位置参数从 {pos_param} 改为 {new_param}",
+                before=f"\\begin{{{float_type}}}{pos_param}",
+                after=f"\\begin{{{float_type}}}{new_param}",
+                success=True,
+            )
+        elif not pos_param:
+            # 没有参数，添加 [htbp]
+            new_param = "[htbp]"
+            insert_pos = target_match.end()
+            modified_content = tex_content[:insert_pos] + new_param + tex_content[insert_pos:]
+            return modified_content, FixResult(
+                defect_id="B1",
+                object_name=float_label,
+                action=f"添加浮动体位置参数 {new_param}",
+                before=f"\\begin{{{float_type}}}",
+                after=f"\\begin{{{float_type}}}{new_param}",
+                success=True,
+            )
+
+    # 策略 2: 在引用点后添加 \FloatBarrier
+    # 查找首次引用该 label 的位置
+    ref_pattern = r'\\(ref|autoref|cref|Cref)\{' + re.escape(float_label) + r'\}'
+    ref_match = re.search(ref_pattern, tex_content)
+
+    if ref_match:
+        # 在引用后添加 \FloatBarrier
+        insert_pos = ref_match.end()
+        # 检查是否已有 \FloatBarrier
+        after_ref = tex_content[insert_pos:insert_pos + 100]
+        if '\\FloatBarrier' not in after_ref:
+            modified_content = tex_content[:insert_pos] + "\n\\FloatBarrier" + tex_content[insert_pos:]
+            return modified_content, FixResult(
+                defect_id="B1",
+                object_name=float_label,
+                action="在引用后添加 \\FloatBarrier 以阻止浮动体继续漂后",
+                before=ref_match.group(0)[:30] + "...",
+                after=ref_match.group(0) + "\n\\FloatBarrier",
+                success=True,
+            )
+
+    return tex_content, None
+
+
+def add_floatbarrier_to_preamble(
+    tex_content: str,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    在导言区添加 placeins 宏包以支持 \FloatBarrier
+    """
+    if '\\usepackage{placeins}' in tex_content:
+        return tex_content, None
+
+    # 在 \begin{document} 前添加
+    match = re.search(r'\\begin\{document\}', tex_content)
+    if match:
+        insert_pos = match.start()
+        modified_content = tex_content[:insert_pos] + "\\usepackage{placeins}\n" + tex_content[insert_pos:]
+        return modified_content, FixResult(
+            defect_id="B1",
+            object_name="导言区",
+            action="添加 placeins 宏包以支持 \\FloatBarrier",
+            before="\\begin{document}",
+            after="\\usepackage{placeins}\n\\begin{document}",
+            success=True,
+        )
+
+    return tex_content, None
+
+
+# ============================================================
+# B2：浮动体大小不适配栏宽
+# ============================================================
+
+def fix_figure_width_mismatch(
+    tex_content: str,
+    figure_label: str,
+    template_type: str = "single_column",
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复图片宽度不适配栏宽问题
+
+    策略优先级:
+    1. 设置宽度为 \linewidth
+    2. 区分单栏/跨栏 (双栏模板)
+    3. 设置高度 + keepaspectratio
+
+    Args:
+        tex_content: .tex 文件内容
+        figure_label: 图片标签
+        template_type: 模板类型 ("single_column" | "double_column")
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    # 定位 figure 环境
+    pattern = r'(\\begin\{(?:figure|figure\*)\}(?:\[[htbp]+\])?.*?)(\\includegraphics(?:\[[^\]]*\])?\{[^}]+\})'
+    matches = list(re.finditer(pattern, tex_content, re.DOTALL))
+
+    target_match = None
+    for match in matches:
+        label_pattern = r'\\label\{' + re.escape(figure_label) + r'\}'
+        label_match = re.search(label_pattern, tex_content[match.start():match.end()])
+        if label_match:
+            target_match = match
+            break
+
+    if not target_match:
+        return tex_content, None
+
+    include_graphic = target_match.group(2)
+
+    # 检查是否已有 \linewidth 宽度
+    if r'\linewidth' in include_graphic or r'\textwidth' in include_graphic:
+        # 宽度已合理设置
+        return tex_content, None
+
+    # 策略 1: 标准化宽度设置
+    # 解析当前宽度参数
+    width_match = re.search(r'width=([^\s,\]]+)', include_graphic)
+
+    if width_match:
+        # 替换现有宽度为 \linewidth
+        new_graphic = re.sub(
+            r'width=[^\s,\]]+',
+            r'width=\\linewidth',
+            include_graphic
+        )
+    else:
+        # 没有 width 参数，添加
+        # 检查是否有可选参数
+        if include_graphic.startswith('\\includegraphics['):
+            # 有可选参数，在 ] 前插入
+            bracket_pos = include_graphic.find(']')
+            new_graphic = include_graphic[:bracket_pos] + ',width=\\linewidth' + include_graphic[bracket_pos:]
+        else:
+            # 没有可选参数，添加
+            new_graphic = include_graphic.replace(
+                '\\includegraphics',
+                '\\includegraphics[width=\\linewidth]'
+            )
+
+    modified_content = tex_content.replace(include_graphic, new_graphic, 1)
+
+    return modified_content, FixResult(
+        defect_id="B2",
+        object_name=figure_label,
+        action="将图片宽度设为 \\linewidth",
+        before=include_graphic[:50] + "...",
+        after=new_graphic[:50] + "...",
+        success=True,
+    )
+
+
+def fix_table_width_mismatch(
+    tex_content: str,
+    table_label: str,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复表格宽度不适配栏宽问题
+
+    策略优先级:
+    1. 将 tabular 改为 tabularx 并设宽度为 \linewidth
+    2. 调整列规格
+    3. 使用 sidewaystable 旋转超宽表格
+
+    Args:
+        tex_content: .tex 文件内容
+        table_label: 表格标签
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    # 定位 table 环境
+    pattern = r'(\\begin\{table\}(?:\[[htbp]+\])?.*?)(\\begin\{tabular\})(\{[^}]+\})(.*?)(\\end\{tabular\})'
+    matches = list(re.finditer(pattern, tex_content, re.DOTALL))
+
+    target_match = None
+    for match in matches:
+        label_pattern = r'\\label\{' + re.escape(table_label) + r'\}'
+        label_match = re.search(label_pattern, tex_content[match.start():match.end()])
+        if label_match:
+            target_match = match
+            break
+
+    if not target_match:
+        return tex_content, None
+
+    tabular_start = target_match.group(2)
+    column_spec = target_match.group(3)
+    table_body = target_match.group(4)
+    tabular_end = target_match.group(5)
+
+    # 检查是否已有宽度设置
+    if target_match.group(1).strip().endswith('{\\linewidth}'):
+        return tex_content, None
+
+    # 策略：改为 tabularx
+    new_column_spec = _convert_to_tabularx_columns(column_spec.strip('{}'))
+
+    old_full = f"\\begin{{tabular}}{column_spec}"
+    new_full = f"\\begin{{tabularx}}{{\\linewidth}}{new_column_spec}"
+
+    modified_content = tex_content.replace(
+        old_full,
+        new_full,
+        1
+    ).replace(
+        "\\end{tabular}",
+        "\\end{tabularx}",
+        1
+    )
+
+    return modified_content, FixResult(
+        defect_id="B2",
+        object_name=table_label,
+        action=f"将 tabular 改为 tabularx，宽度设为 \\linewidth",
+        before=f"\\begin{{tabular}}{column_spec}",
+        after=f"\\begin{{tabularx}}{{\\linewidth}}{new_column_spec}",
+        success=True,
+    )
+
+
+def _convert_to_tabularx_columns(column_spec: str) -> str:
+    """
+    将 tabular 列规格转换为 tabularx 列规格
+    策略：将最宽的文本列改为 X 列
+    """
+    spec = column_spec.strip('{}')
+
+    # 统计列类型
+    text_columns = []
+    for i, c in enumerate(spec):
+        if c in 'lrc':
+            text_columns.append((i, c))
+
+    if not text_columns:
+        return column_spec
+
+    # 将最后一个文本列改为 X 列
+    last_text_idx, _ = text_columns[-1]
+    new_spec = spec[:last_text_idx] + 'X' + spec[last_text_idx + 1:]
+
+    return '{' + new_spec + '}'
+
+
+def fix_wide_float_in_double_column(
+    tex_content: str,
+    float_label: str,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    在双栏模板中修复宽浮动体
+
+    策略:
+    1. 将 figure 改为 figure* (跨栏)
+    2. 将 table 改为 table*
+    3. 宽度设为 \\textwidth
+
+    Args:
+        tex_content: .tex 文件内容
+        float_label: 浮动体标签
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    # 确定浮动体类型
+    is_figure = "fig" in float_label.lower()
+    float_type = "figure" if is_figure else "table"
+
+    # 查找浮动体环境
+    pattern = r'\\begin\{' + float_type + r'\}(\[[htbp]+\])?'
+    matches = list(re.finditer(pattern, tex_content))
+
+    target_match = None
+    for match in matches:
+        label_pattern = r'\\label\{' + re.escape(float_label) + r'\}'
+        after_start = match.end()
+        label_match = re.search(label_pattern, tex_content[after_start:after_start + 500])
+        if label_match:
+            target_match = match
+            break
+
+    if not target_match:
+        return tex_content, None
+
+    # 改为跨栏环境
+    old_env = f"\\begin{{{float_type}}}"
+    new_env = f"\\begin{{{float_type}*}}"
+
+    modified_content = tex_content.replace(old_env, new_env, 1)
+    modified_content = modified_content.replace(
+        f"\\end{{{float_type}}}",
+        f"\\end{{{float_type}*}}",
+        1
+    )
+
+    return modified_content, FixResult(
+        defect_id="B2",
+        object_name=float_label,
+        action=f"将 {float_type} 改为 {float_type}* 以跨栏显示",
+        before=old_env,
+        after=new_env,
+        success=True,
+    )
+
+
+# ============================================================
+# B3：浮动体连续堆叠
+# ============================================================
+
+def fix_float_clustering(
+    tex_content: str,
+    float_labels: List[str],
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复浮动体连续堆叠问题
+
+    策略优先级:
+    1. 分散浮动体位置参数
+    2. 在浮动体之间插入正文
+    3. 使用 \FloatBarrier 控制
+
+    Args:
+        tex_content: .tex 文件内容
+        float_labels: 堆叠的浮动体标签列表
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    if len(float_labels) < 2:
+        return tex_content, None
+
+    # 策略 1: 为每个浮动体分配不同的位置偏好
+    position_prefs = ["[t]", "[b]", "[p]", "[htbp]"]
+    changes_made = []
+
+    for i, label in enumerate(float_labels[:len(position_prefs)]):
+        # 确定浮动体类型
+        float_type = "figure" if "fig" in label.lower() else "table"
+        pattern = r'\\begin\{' + float_type + r'\}(\[[^\]]*\])?'
+        match = re.search(pattern, tex_content)
+
+        if match:
+            current_param = match.group(1) if match.group(1) else ""
+            new_param = position_prefs[i]
+
+            if current_param != new_param:
+                if current_param:
+                    tex_content = tex_content[:match.start(1)] + new_param + tex_content[match.end(1):]
+                else:
+                    insert_pos = match.end()
+                    tex_content = tex_content[:insert_pos] + new_param + tex_content[insert_pos:]
+
+                changes_made.append({
+                    "label": label,
+                    "before": current_param or f"\\begin{{{float_type}}}",
+                    "after": f"\\begin{{{float_type}}}{new_param}",
+                })
+
+    if changes_made:
+        return tex_content, FixResult(
+            defect_id="B3",
+            object_name=", ".join([c["label"] for c in changes_made]),
+            action="分散浮动体位置参数以避免堆叠",
+            before="; ".join([c["before"] for c in changes_made]),
+            after="; ".join([c["after"] for c in changes_made]),
+            success=True,
+        )
+
+    return tex_content, None
+
+
+# ============================================================
+# B4：浮动体跨页分裂
+# ============================================================
+
+def fix_split_table(
+    tex_content: str,
+    table_label: str,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复长表格跨页分裂问题
+
+    策略优先级:
+    1. 将 table + tabular 改为 longtable
+    2. 强制表格不跨页 [!h]
+    3. 拆分过大的表格
+
+    Args:
+        tex_content: .tex 文件内容
+        table_label: 表格标签
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    # 定位 table 环境
+    pattern = r'(\\begin\{table\}(?:\[[^\]]*\])?.*?)(\\begin\{tabular\})(\{[^}]+\})(.*?)(\\end\{tabular\})(.*?\\end\{table\})'
+    matches = list(re.finditer(pattern, tex_content, re.DOTALL))
+
+    target_match = None
+    for match in matches:
+        label_pattern = r'\\label\{' + re.escape(table_label) + r'\}'
+        label_match = re.search(label_pattern, tex_content[match.start():match.end()])
+        if label_match:
+            target_match = match
+            break
+
+    if not target_match:
+        return tex_content, None
+
+    full_table = target_match.group(0)
+    table_start = target_match.group(1)
+    tabular_start = target_match.group(2)
+    column_spec = target_match.group(3)
+    table_body = target_match.group(4)
+    tabular_end = target_match.group(5)
+    table_end = target_match.group(6)
+
+    # 检查是否已有 caption 和 label
+    caption_match = re.search(r'\\caption\{([^}]+)\}', table_start + table_body)
+    label_match = re.search(r'\\label\{([^}]+)\}', table_start + table_body)
+
+    caption_text = caption_match.group(1) if caption_match else "Long Table"
+    label_text = label_match.group(1) if label_match else table_label
+
+    # 策略 1: 改为 longtable
+    # 提取表头 (第一行)
+    header_match = re.search(r'([^\\]*?)(?:\\hline)?\s*([^\\]+?)\s*\\\\', table_body)
+    if header_match:
+        header_row = header_match.group(2).strip()
+
+        longtable_content = f"""\\begin{{longtable}}{column_spec}
+\\caption{{{caption_text}}} \\label{{{label_text}}} \\\\
+\\hline
+{header_row} \\\\
+\\hline
+\\endfirsthead
+\\hline
+{header_row} \\\\
+\\hline
+\\endhead
+\\hline \\multicolumn{{{len(column_spec.strip("{}"))}}}{{r}}{{Continued on next page}} \\\\
+\\endfoot
+\\hline
+\\endlastfoot
+"""
+        # 添加表体 (去除第一行)
+        body_lines = table_body.split('\\\\')
+        if len(body_lines) > 1:
+            longtable_content += '\n'.join(body_lines[1:])
+
+        longtable_content += "\n\\end{longtable}"
+
+        modified_content = tex_content.replace(full_table, longtable_content, 1)
+
+        return modified_content, FixResult(
+            defect_id="B4",
+            object_name=table_label,
+            action="将 table+tabular 改为 longtable 以支持跨页",
+            before=f"\\begin{{table}}...\\end{{tabular}}...\\end{{table}}",
+            after=f"\\begin{{longtable}}{column_spec}...\\end{{longtable}}",
+            success=True,
+        )
+
+    return tex_content, None
+
+
+def fix_split_figure(
+    tex_content: str,
+    figure_label: str,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复图片组跨页分裂问题
+
+    策略:
+    1. 强制图片不跨页 [!h]
+    2. 拆分过大的图片组为多个独立 figure
+
+    Args:
+        tex_content: .tex 文件内容
+        figure_label: 图片标签
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    # 定位 figure 环境
+    pattern = r'\\begin\{figure\}(\[[^\]]*\])?'
+    matches = list(re.finditer(pattern, tex_content))
+
+    target_match = None
+    for match in matches:
+        label_pattern = r'\\label\{' + re.escape(figure_label) + r'\}'
+        after_start = match.end()
+        label_match = re.search(label_pattern, tex_content[after_start:after_start + 500])
+        if label_match:
+            target_match = match
+            break
+
+    if not target_match:
+        return tex_content, None
+
+    current_param = target_match.group(1) if target_match.group(1) else ""
+
+    # 策略：添加 [!h] 强制位置
+    new_param = "[!h]"
+    if current_param != new_param:
+        if current_param:
+            modified_content = tex_content[:target_match.start(1)] + new_param + tex_content[target_match.end(1):]
+        else:
+            insert_pos = target_match.end()
+            modified_content = tex_content[:insert_pos] + new_param + tex_content[insert_pos:]
+
+        return modified_content, FixResult(
+            defect_id="B4",
+            object_name=figure_label,
+            action=f"添加 [!h] 强制图片放置在此处以避免分裂",
+            before=f"\\begin{{figure}}{current_param}",
+            after=f"\\begin{{figure}}{new_param}",
+            success=True,
+        )
+
+    return tex_content, None
+
+
+# ============================================================
+# 主修复函数
+# ============================================================
+
+def fix_float_defects(
+    tex_file_path: str,
+    defects: List[Dict[str, Any]],
+    template_type: str = "single_column",
+) -> FloatFixReport:
+    """
+    修复所有 Category B 缺陷
+
+    Args:
+        tex_file_path: .tex 文件路径
+        defects: 缺陷列表，每个缺陷包含:
+            - defect_id: B1, B2, B3, B4
+            - page: 页码
+            - object: 对象名称 (图表标签)
+            - description: 描述
+            - ref_page: 引用页码 (B1 需要)
+        template_type: 模板类型 ("single_column" | "double_column")
+
+    Returns:
+        FloatFixReport: 修复报告
+    """
+    tex_path = Path(tex_file_path)
+    if not tex_path.exists():
+        return FloatFixReport(
+            status="failed",
+            unresolved=[f"文件不存在：{tex_file_path}"]
+        )
+
+    try:
+        tex_content = tex_path.read_text(encoding='utf-8')
+    except (OSError, UnicodeDecodeError) as e:
+        return FloatFixReport(
+            status="failed",
+            unresolved=[f"无法读取文件 {tex_file_path}: {e}"]
+        )
+
+    modified_files = set()
+    changes = []
+    unresolved = []
+
+    # 检查是否需要添加 placeins 宏包
+    needs_placeins = any(d.get("defect_id") == "B1" for d in defects)
+    if needs_placeins and '\\usepackage{placeins}' not in tex_content:
+        new_content, fix_result = add_floatbarrier_to_preamble(tex_content)
+        if fix_result and new_content != tex_content:
+            tex_content = new_content
+            changes.append(fix_result)
+            modified_files.add(str(tex_path))
+
+    for defect in defects:
+        defect_id = defect.get("defect_id", "")
+        page = defect.get("page", 0)
+        object_name = defect.get("object", "")
+        ref_page = defect.get("ref_page", 0)
+
+        new_content = tex_content
+        fix_result = None
+
+        if defect_id == "B1":
+            # 浮动体远离首次引用
+            new_content, fix_result = fix_float_reference_distance(
+                tex_content,
+                float_label=object_name,
+                ref_page=ref_page,
+                float_page=page,
+            )
+
+        elif defect_id == "B2":
+            # 浮动体大小不适配
+            if "fig" in object_name.lower():
+                new_content, fix_result = fix_figure_width_mismatch(
+                    tex_content,
+                    figure_label=object_name,
+                    template_type=template_type,
+                )
+            elif "tab" in object_name.lower():
+                new_content, fix_result = fix_table_width_mismatch(
+                    tex_content,
+                    table_label=object_name,
+                )
+
+        elif defect_id == "B3":
+            # 浮动体连续堆叠 - 需要收集所有堆叠的标签
+            # 简化实现：单个处理
+            new_content, fix_result = fix_float_clustering(
+                tex_content,
+                float_labels=[object_name],
+            )
+
+        elif defect_id == "B4":
+            # 浮动体跨页分裂
+            if "fig" in object_name.lower():
+                new_content, fix_result = fix_split_figure(
+                    tex_content,
+                    figure_label=object_name,
+                )
+            elif "tab" in object_name.lower():
+                new_content, fix_result = fix_split_table(
+                    tex_content,
+                    table_label=object_name,
+                )
+
+        # 检查修复是否成功
+        if fix_result and new_content != tex_content:
+            tex_content = new_content
+            fix_result.page = page
+            fix_result.line_number = defect.get("line_number")
+            changes.append(fix_result)
+            modified_files.add(str(tex_path))
+        else:
+            unresolved.append(
+                f"{defect_id} ({object_name or '未知对象'}): 无法自动修复，可能需要人工调整"
+            )
+
+    # 写入修改后的内容
+    if modified_files:
+        try:
+            tex_path.write_text(tex_content, encoding='utf-8')
+        except OSError as e:
+            unresolved.append(f"无法写入文件 {tex_path}: {e}")
+            return FloatFixReport(
+                status="failed",
+                modified_files=list(modified_files),
+                changes=changes,
+                unresolved=unresolved,
+            )
+
+    status = "success" if not unresolved else ("partial" if changes else "failed")
+
+    return FloatFixReport(
+        status=status,
+        modified_files=list(modified_files),
+        changes=changes,
+        unresolved=unresolved,
+    )
+
+
+# ============================================================
+# CLI 入口
+# ============================================================
+
+def main():
+    """命令行接口"""
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(
+        description="Fix Category B float defects in LaTeX documents"
+    )
+    parser.add_argument(
+        "tex_file",
+        help="Path to .tex file"
+    )
+    parser.add_argument(
+        "--defects",
+        type=str,
+        help="JSON string or file path containing defect list"
+    )
+    parser.add_argument(
+        "--template",
+        type=str,
+        default="single_column",
+        choices=["single_column", "double_column"],
+        help="Template type"
+    )
+    parser.add_argument(
+        "--json",
+        "-j",
+        action="store_true",
+        help="Output JSON report"
+    )
+
+    args = parser.parse_args()
+
+    # 解析缺陷列表
+    defects = []
+    if args.defects:
+        if Path(args.defects).exists():
+            with open(args.defects, 'r', encoding='utf-8') as f:
+                defects = json.load(f)
+        else:
+            defects = json.loads(args.defects)
+
+    # 执行修复
+    report = fix_float_defects(args.tex_file, defects, template_type=args.template)
+
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2, ensure_ascii=False))
+    else:
+        print(f"\nFloat Fix Report")
+        print("=" * 50)
+        print(f"Status: {report.status}")
+        print(f"Modified files: {report.modified_files}")
+        print(f"Changes: {len(report.changes)}")
+        for change in report.changes:
+            print(f"  - [{change.defect_id}] {change.object_name}: {change.action}")
+        if report.unresolved:
+            print(f"\nUnresolved: {len(report.unresolved)}")
+            for u in report.unresolved:
+                print(f"  - {u}")
+
+
+if __name__ == "__main__":
+    main()