Latex Translate Zh

__pycache__/
*.pyc
*.pyo
*.aux
*.log
*.out
*.toc
*.bbl
*.blg
*.fdb_latexmk
*.fls
*.synctex.gz
*.nav
*.snm
*.vrb
*.pdf
*.bak
*.backup
*~
.DS_Store

3.10

MIT License

Copyright (c) 2026

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.

[project]
name = "latex-translate-zh"
version = "0.2.1"
description = "LaTeX论文翻译成中文并编译PDF — AI agent skill for translating LaTeX papers to Chinese"
license = { text = "MIT" }
requires-python = ">=3.10"

"""
将翻译结果回填到 LaTeX 文件中。

读取翻译 JSON（block_id → translation），在指定项目中
查找每个 block_id 对应的源文本并替换为译文。

Usage:
    uv run python backfill_blocks.py /path/to/project translations.json

translations.json 格式:
    {
      "blocks": [
        {"block_id": "blk_0001", "translation": "中文译文"},
        ...
      ]
    }
    或 JSONL 格式（每行一个翻译块）。
"""

import argparse
import json
import re
import sys
from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path
from typing import Optional


def _find_matching_brace(s: str, pos: int) -> int:
    """Find matching closing brace/bracket. pos points to the opening char."""
    open_char = s[pos]
    close_char = '}' if open_char == '{' else ']'
    depth = 1
    i = pos + 1
    while i < len(s) and depth > 0:
        if s[i] == open_char:
            depth += 1
        elif s[i] == close_char:
            depth -= 1
        if depth == 0:
            return i
        i += 1
    return len(s)


def _looks_like_block_id(value: str) -> bool:
    return bool(re.fullmatch(r"(blk_\d+|[A-Za-z0-9_.:-]+)", value))


def _normalize_translation(value: object, block_id: str = "") -> str:
    """Normalize model-produced translation strings.

    Some agents emit literal "\\n" inside JSON values instead of JSON newlines.
    Convert only standalone escaped newlines, not LaTeX commands such as
    \newcommand.
    """
    if value is None:
        return ""
    text = str(value)
    text = re.sub(r"(?<!\\)\\n(?![A-Za-z@])", "\n", text)
    text = re.sub(r"(?<!\\)\\t(?![A-Za-z@])", "\t", text)
    return text


def _add_translation(translations: dict[str, str], block_id: object, value: object) -> None:
    if not isinstance(block_id, str) or not _looks_like_block_id(block_id):
        return
    text = _normalize_translation(value, block_id)
    if text:
        translations[block_id] = text


def _collect_translations(data: object, translations: dict[str, str]) -> None:
    """Accept common translation JSON shapes.

    Supported:
      {"blocks": [{"block_id": "blk_0001", "translation": "..."}]}
      [{"block_id": "blk_0001", "translation": "..."}]
      {"blk_0001": "..."}
      {"intro.tex": {"blk_0001": "..."}}
      {"intro.tex": [{"block_id": "blk_0001", "translation": "..."}]}
    """
    if isinstance(data, list):
        for item in data:
            _collect_translations(item, translations)
        return

    if not isinstance(data, dict):
        return

    if "block_id" in data:
        value = data.get("translation", data.get("translated_text", data.get("target_text")))
        _add_translation(translations, data.get("block_id"), value)
        return

    if "blocks" in data:
        _collect_translations(data["blocks"], translations)
        return

    for key, value in data.items():
        if isinstance(value, str):
            _add_translation(translations, key, value)
        elif isinstance(value, (dict, list)):
            _collect_translations(value, translations)


def load_translations(trans_file: Path) -> dict[str, str]:
    """Load translations from JSON or JSONL file."""
    text = trans_file.read_text(encoding="utf-8", errors="ignore").strip()

    translations: dict[str, str] = {}

    # Try JSON array/object
    try:
        data = json.loads(text)
        _collect_translations(data, translations)
        return translations
    except json.JSONDecodeError:
        pass

    # Try JSONL
    for line in text.split('\n'):
        line = line.strip()
        if not line:
            continue
        try:
            item = json.loads(line)
            _collect_translations(item, translations)
        except (json.JSONDecodeError, KeyError):
            continue

    return translations


def _command_counts(text: str) -> dict[str, int]:
    commands = [
        r"\\begin", r"\\end", r"\\label", r"\\ref", r"\\eqref",
        r"\\cite", r"\\citep", r"\\citet", r"\\cref", r"\\Cref",
        r"\\includegraphics",
    ]
    return {cmd: len(re.findall(re.escape(cmd) + r"\b", text)) for cmd in commands}


def _all_command_counts(text: str) -> dict[str, int]:
    counts: dict[str, int] = {}
    for name in re.findall(r"\\[A-Za-z@]+\*?", text):
        counts[name] = counts.get(name, 0) + 1
    return counts


def _has_suspicious_escape(text: str) -> bool:
    """Detect common escaped-control leftovers from generated JSON."""
    return bool(re.search(r"(?<!\\)\\[nt](?![A-Za-z@])", text))


def validate_translation(source_text: str, translation: str) -> tuple[bool, str]:
    """Reject translations that are likely to break LaTeX structure."""
    if not translation.strip():
        return False, "译文为空"

    if _has_suspicious_escape(translation):
        return False, "译文包含疑似未解码的 \\n 或 \\t"

    src_counts = _command_counts(source_text)
    dst_counts = _command_counts(translation)
    changed = [
        f"{cmd}: {src_counts[cmd]}->{dst_counts[cmd]}"
        for cmd in src_counts
        if src_counts[cmd] != dst_counts[cmd]
    ]
    if changed:
        return False, "LaTeX 命令数量变化: " + ", ".join(changed)

    src_all = _all_command_counts(source_text)
    dst_all = _all_command_counts(translation)
    if src_all != dst_all:
        names = sorted(set(src_all) | set(dst_all))
        changed_all = [
            f"{name}: {src_all.get(name, 0)}->{dst_all.get(name, 0)}"
            for name in names
            if src_all.get(name, 0) != dst_all.get(name, 0)
        ]
        return False, "LaTeX 宏集合变化: " + ", ".join(changed_all[:12])

    if source_text.count("$") != translation.count("$"):
        return False, "数学模式 $ 数量变化"

    if source_text.count("\\\\") != translation.count("\\\\"):
        return False, r"换行命令 \\ 数量变化"

    if re.fullmatch(r"\[?[!htbpH,\s]+\]?", source_text.strip()):
        return False, "疑似布局参数，不应回填"

    return True, ""


def load_source_blocks(blocks_file: Optional[Path], translations: dict[str, str]) -> dict[str, dict]:
    """Load source blocks to get source_text and file info."""
    if not blocks_file or not blocks_file.exists():
        return {}

    text = blocks_file.read_text(encoding="utf-8", errors="ignore").strip()
    blocks: dict[str, dict] = {}

    try:
        data = json.loads(text)
        items = data.get("blocks", data if isinstance(data, list) else [])
        for item in items:
            if item.get("block_id") in translations:
                blocks[item["block_id"]] = item
    except json.JSONDecodeError:
        for line in text.split('\n'):
            line = line.strip()
            if not line:
                continue
            try:
                item = json.loads(line)
                if item.get("block_id") in translations:
                    blocks[item["block_id"]] = item
            except json.JSONDecodeError:
                continue

    return blocks


def backfill_file(
    filepath: Path,
    file_translations: dict[str, str],
    source_info: dict[str, dict],
) -> int:
    """Replace source text with translations in a file. Returns number of replacements."""
    content = filepath.read_text(encoding="utf-8", errors="ignore")
    replaced = 0

    # Sort blocks by source_text length (longest first) to avoid partial matches
    for block_id, translation in sorted(
        file_translations.items(),
        key=lambda x: len(source_info.get(x[0], {}).get("source_text", "")),
        reverse=True,
    ):
        info = source_info.get(block_id, {})
        source_text = info.get("source_text", "")

        if not source_text:
            continue

        ok, reason = validate_translation(source_text, translation)
        if not ok:
            print(f"  [SKIP] {block_id}: {reason}", file=sys.stderr)
            continue

        # Only replace if source_text appears exactly once
        count = content.count(source_text)
        if count == 1:
            content = content.replace(source_text, translation, 1)
            replaced += 1
        elif count > 1:
            # Source text appears multiple times - potentially ambiguous
            # For safety, skip ambiguous replacements
            print(f"  [SKIP] {block_id}: 源文本出现 {count} 次，跳过以避免歧义替换", file=sys.stderr)
        else:
            print(f"  [SKIP] {block_id}: 源文本未找到", file=sys.stderr)

    if replaced > 0:
        filepath.write_text(content, encoding="utf-8")
        print(f"  [OK] {filepath.name}: 替换 {replaced} 处", file=sys.stderr)

    return replaced


def backfill_project(
    project_dir: Path,
    translations: dict[str, str],
    source_blocks: dict[str, dict],
    parallel: bool = True,
) -> int:
    """Apply all translations to project files. Files are processed in parallel."""
    # Group translations by file
    by_file: dict[str, dict[str, str]] = {}
    for block_id, translation in translations.items():
        info = source_blocks.get(block_id, {})
        filename = info.get("file", "")
        if filename:
            by_file.setdefault(filename, {})[block_id] = translation

    if not by_file:
        print("[WARN] 没有可供回填的翻译块", file=sys.stderr)
        return 0

    total = 0
    file_count = len(by_file)

    if parallel and file_count > 1:
        print(f"  并行写入 {file_count} 个文件...", file=sys.stderr)
        with ThreadPoolExecutor(max_workers=min(file_count, 8)) as executor:
            futures = {
                executor.submit(
                    _backfill_one_file, project_dir, rel_path, file_trans, source_blocks
                ): rel_path
                for rel_path, file_trans in by_file.items()
            }
            for future in as_completed(futures):
                rel_path = futures[future]
                try:
                    n = future.result()
                    total += n
                except Exception as e:
                    print(f"  [ERR] {rel_path}: {e}", file=sys.stderr)
    else:
        for rel_path, file_trans in by_file.items():
            filepath = project_dir / rel_path
            if filepath.is_file():
                total += backfill_file(filepath, file_trans, source_blocks)
            else:
                print(f"  [MISS] 文件不存在: {rel_path}", file=sys.stderr)

    return total


def _backfill_one_file(
    project_dir: Path,
    rel_path: str,
    file_trans: dict[str, str],
    source_info: dict[str, dict],
) -> int:
    """Backfill a single file (for parallel execution)."""
    filepath = project_dir / rel_path
    if not filepath.is_file():
        print(f"  [MISS] 文件不存在: {rel_path}", file=sys.stderr)
        return 0
    return backfill_file(filepath, file_trans, source_info)


def main():
    parser = argparse.ArgumentParser(
        description="将翻译结果回填到 LaTeX 文件中",
    )
    parser.add_argument(
        "project_dir",
        nargs="?",
        help="LaTeX 项目目录（复制出的工作目录）",
    )
    parser.add_argument(
        "translations",
        nargs="?",
        help="翻译 JSON 文件（block_id → translation）",
    )
    parser.add_argument("-d", "--dir", dest="project_dir_opt", help="LaTeX 项目目录")
    parser.add_argument("-t", "--translations-file", dest="translations_opt", help="翻译 JSON 文件")
    parser.add_argument(
        "--blocks",
        help="提取阶段输出的 blocks JSON 文件（提供源文本定位信息）",
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="仅检查不实际写入",
    )
    parser.add_argument(
        "--no-parallel",
        action="store_true",
        help="禁用并行写入（串行模式）",
    )
    args = parser.parse_args()

    project_dir = args.project_dir or args.project_dir_opt
    translations_arg = args.translations or args.translations_opt
    if not project_dir:
        parser.error("需要提供 project_dir 或 -d/--dir")
    if not translations_arg:
        parser.error("需要提供 translations 或 -t/--translations-file")

    root = Path(project_dir).resolve()
    if not root.is_dir():
        print(f"[ERROR] 目录不存在: {args.project_dir}", file=sys.stderr)
        sys.exit(1)

    trans_file = Path(translations_arg)
    if not trans_file.is_file():
        print(f"[ERROR] 翻译文件不存在: {translations_arg}", file=sys.stderr)
        sys.exit(1)

    translations = load_translations(trans_file)
    if not translations:
        print("[ERROR] 未加载到任何翻译", file=sys.stderr)
        sys.exit(1)

    blocks_file = Path(args.blocks) if args.blocks else None
    source_blocks = load_source_blocks(blocks_file, translations)

    print(f"加载 {len(translations)} 个翻译块，其中 {len(source_blocks)} 个有源文件信息", file=sys.stderr)

    if args.dry_run:
        print("\n[Dry run] 以下翻译将回填:", file=sys.stderr)
        for block_id, trans in translations.items():
            info = source_blocks.get(block_id, {})
            src = info.get("source_text", "?")[:60]
            print(f"  {block_id}: {src} → {trans[:60]}", file=sys.stderr)
        sys.exit(0)

    replaced = backfill_project(root, translations, source_blocks,
                                 parallel=not args.no_parallel)
    print(f"\n回填完成: {replaced} 处替换", file=sys.stderr)


if __name__ == "__main__":
    main()

"""
检查 CJK 字体的粗体/斜体变体支持，输出 xeCJK fallback 配置。

通过 fc-list 查询指定字体的 Bold、Italic、BoldItalic 子面，
对缺失的变体生成 AutoFakeBold/AutoFakeSlant 配置。

Usage:
    uv run python check_cjk_variants.py "Noto Serif CJK SC"
    uv run python check_cjk_variants.py "Noto Serif CJK SC" --json
    uv run python check_cjk_variants.py "Noto Serif CJK SC" --code-only
"""

import argparse
import json
import re
import subprocess
import sys


# ──────────────────────────── Font Variant Detection ────────────────────────────

def get_font_styles(font_name: str) -> dict[str, str]:
    """
    通过 fc-list 查询字体的所有变体 (style → file path)。

    返回:
        'Regular':    /path/to/font.ttc
        'Bold':       /path/to/font.ttc  (or absent if not found)
        'Italic':     /path/to/font.ttc  (or absent)
        'Bold Italic': /path/to/font.ttc (or absent)
    """
    styles = {}
    try:
        result = subprocess.run(
            ['fc-list', font_name, 'style', 'file'],
            capture_output=True, text=True, timeout=15,
        )
        if result.returncode != 0:
            return styles

        for line in result.stdout.splitlines():
            # Format: /path/to/font.ttc: style=Regular
            m = re.match(r'^(.+?):\s*style=(.+?)(?:,\w+)*\s*$', line)
            if m:
                file_path, style = m.group(1).strip(), m.group(2).strip()
                styles[style] = file_path
    except (FileNotFoundError, subprocess.TimeoutExpired):
        pass
    return styles


def check_variants(font_name: str) -> dict:
    """
    检查字体变体支持。

    返回:
        font_name:    查询的字体名
        has_bold:     True/False
        has_italic:   True/False
        has_bold_italic: True/False
        styles:       所有检测到的 style 映射
        variants:     具体变体配置建议
        auto_fake_bold:  推荐的 AutoFakeBold 值（None 表示不需要）
        auto_fake_slant: 推荐的 AutoFakeSlant 值
    """
    styles = get_font_styles(font_name)

    style_names = set(s.lower() for s in styles.keys())

    has_bold = any(kw in style_names for kw in ('bold', 'black', 'heavy', 'semibold', 'demibold'))
    has_italic = any(kw in style_names for kw in ('italic', 'oblique', 'slanted'))
    has_bold_italic = any(
        ('bold' in s and ('italic' in s or 'oblique' in s)) for s in style_names
    )

    # 推荐配置
    variants = {}
    if has_bold:
        # 找到实际 Bold style 名
        for s in styles:
            if any(kw in s.lower() for kw in ('bold', 'black', 'heavy', 'semibold', 'demibold')):
                variants['BoldFont'] = font_name
                variants['BoldFeatures'] = f'{{Style={s}}}'
                break

    if has_italic:
        for s in styles:
            if any(kw in s.lower() for kw in ('italic', 'oblique', 'slanted')):
                variants['ItalicFont'] = font_name
                variants['ItalicFeatures'] = f'{{Style={s}}}'
                break

    if has_bold_italic:
        for s in styles:
            if 'bold' in s.lower() and ('italic' in s.lower() or 'oblique' in s.lower()):
                variants['BoldItalicFont'] = font_name
                variants['BoldItalicFeatures'] = f'{{Style={s}}}'
                break

    # AutoFake 建议值
    auto_fake_bold = 2.5 if not has_bold else None
    auto_fake_slant = 0.167 if not has_italic else None

    return {
        'font_name': font_name,
        'has_bold': has_bold,
        'has_italic': has_italic,
        'has_bold_italic': has_bold_italic,
        'styles': {k: v for k, v in styles.items()},
        'variants': variants,
        'auto_fake_bold': auto_fake_bold,
        'auto_fake_slant': auto_fake_slant,
    }


# ──────────────────────────── Output Formatting ────────────────────────────

def _format_font_options(variants: dict, auto_fake_bold: float | None,
                         auto_fake_slant: float | None, indent: str = '') -> str:
    """生成 xeCJK 字体选项（用于 setCJKmainfont 的 [] 内）。"""
    parts = []
    for key in ('BoldFont', 'ItalicFont', 'BoldItalicFont'):
        if key in variants:
            feat_key = key.replace('Font', 'Features')
            style_val = variants.get(feat_key, f'{{Style={variants[key]}}}')
            parts.append(f"{indent}  {key}={{{variants[key]}}},")
    if auto_fake_bold is not None:
        parts.append(f"{indent}  AutoFakeBold={{{auto_fake_bold}}},")
    if auto_fake_slant is not None:
        parts.append(f"{indent}  AutoFakeSlant={{{auto_fake_slant}}},")
    return "\n".join(parts)


def format_result(result: dict, json_mode: bool = False, code_only: bool = False) -> str:
    """格式化输出版本检查结果。"""
    if json_mode:
        return json.dumps({
            'font_name': result['font_name'],
            'has_bold': result['has_bold'],
            'has_italic': result['has_italic'],
            'has_bold_italic': result['has_bold_italic'],
            'auto_fake_bold': result['auto_fake_bold'],
            'auto_fake_slant': result['auto_fake_slant'],
            'detected_styles': list(result['styles'].keys()),
        }, ensure_ascii=False)

    lines = []
    fname = result['font_name']
    lines.append(f"字体:               {fname}")
    lines.append(f"检测到 {len(result['styles'])} 种变体: {', '.join(result['styles'].keys())}")

    bold_mark = "✓" if result['has_bold'] else "✗"
    italic_mark = "✓" if result['has_italic'] else "✗"
    bi_mark = "✓" if result['has_bold_italic'] else "✗"
    lines.append(f"Bold:               {bold_mark}")
    lines.append(f"Italic:             {italic_mark}")
    lines.append(f"BoldItalic:         {bi_mark}")

    # 推荐配置
    sections = []
    if result['auto_fake_bold'] is not None or result['auto_fake_slant'] is not None:
        xe = []
        if result['auto_fake_bold'] is not None:
            xe.append(f"AutoFakeBold={{{result['auto_fake_bold']}}}")
        if result['auto_fake_slant'] is not None:
            xe.append(f"AutoFakeSlant={{{result['auto_fake_slant']}}}")
        sections.append("\\xeCJKsetup{" + ", ".join(xe) + "}")

    # 字体级配置
    if result['variants'] or result['auto_fake_bold'] is not None or result['auto_fake_slant'] is not None:
        opts = _format_font_options(result['variants'],
                                     result['auto_fake_bold'],
                                     result['auto_fake_slant'])
        sections.append(f"\\setCJKmainfont{{{fname}}}[\n{opts}\n]")

    if code_only:
        return "\n".join(sections)

    if sections:
        lines.append(f"\n推荐配置:")
        lines.append("\n".join(sections))
    else:
        lines.append(f"\n无需额外配置（所有变体均已提供）。")

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="检查 CJK 字体的粗体/斜体变体支持",
    )
    parser.add_argument(
        'font_name',
        help='CJK 字体名称（如 "Noto Serif CJK SC"）',
    )
    parser.add_argument(
        '--json', action='store_true',
        help='以 JSON 格式输出',
    )
    parser.add_argument(
        '--code-only', action='store_true',
        help='仅输出 LaTeX 代码行',
    )
    args = parser.parse_args()

    result = check_variants(args.font_name)
    print(format_result(result, json_mode=args.json, code_only=args.code_only))


if __name__ == '__main__':
    main()

"""
LaTeX Compilation Script - 中文学位论文编译器 (xelatex/lualatex)

默认行为:
    使用 latexmk + XeLaTeX 自动处理所有依赖（bibtex/biber、交叉引用、
    索引、术语表），并自动决定最优编译次数。这是中文论文的推荐方案。

Usage:
    uv run python compile.py main.tex                       # 默认: latexmk + xelatex
    uv run python compile.py main.tex --compiler xelatex    # 显式指定编译器
    uv run python compile.py main.tex --recipe xelatex-bibtex  # 传统 BibTeX
    uv run python compile.py main.tex --recipe xelatex-biber   # 现代 biblatex
    uv run python compile.py main.tex --watch               # 监视模式
    uv run python compile.py main.tex --clean               # 清理辅助文件

Recipes (中文论文推荐 XeLaTeX/LuaLaTeX):
    latexmk          - LaTeXmk + XeLaTeX 自动处理 (默认 - 推荐)
    xelatex          - XeLaTeX 单次编译
    lualatex         - LuaLaTeX 单次编译
    xelatex-bibtex   - xelatex -> bibtex -> xelatex*2 (传统)
    xelatex-biber    - xelatex -> biber -> xelatex*2 (现代 biblatex)
    lualatex-bibtex  - lualatex -> bibtex -> lualatex*2
    lualatex-biber   - lualatex -> biber -> lualatex*2
"""

import argparse
import json
import platform
import re
import shutil
import subprocess
import sys
from pathlib import Path
from typing import Optional


class LaTeXCompiler:
    """Unified LaTeX compilation with multiple recipes."""

    COMPILERS = {"pdflatex", "xelatex", "lualatex"}

    # Default recipe: latexmk with XeLaTeX for Chinese documents (best practice)
    # latexmk auto-detects bibtex/biber needs and runs the correct number of passes
    DEFAULT_RECIPE = "latexmk"

    # Recipes matching VS Code LaTeX Workshop configuration
    # Chinese thesis: XeLaTeX/LuaLaTeX recommended for proper CJK support
    # Recommended workflow:
    #   - latexmk (default): Auto-detect and handle all dependencies with XeLaTeX
    #   - xelatex-bibtex: Traditional BibTeX workflow (legacy .bst styles)
    #   - xelatex-biber: Modern biblatex + biber workflow (recommended for new theses)
    RECIPES = {
        # Single compilation (quick builds)
        "xelatex": ["xelatex"],
        "lualatex": ["lualatex"],
        "latexmk": ["latexmk-xelatex"],  # Default: XeLaTeX + auto-handles bibtex/biber
        # Full workflows (explicit control over compilation steps)
        "xelatex-bibtex": ["xelatex", "bibtex", "xelatex", "xelatex"],
        "xelatex-biber": ["xelatex", "biber", "xelatex", "xelatex"],
        "lualatex-bibtex": ["lualatex", "bibtex", "lualatex", "lualatex"],
        "lualatex-biber": ["lualatex", "biber", "lualatex", "lualatex"],
    }

    # Patterns indicating Chinese content
    CHINESE_PATTERNS = [
        r"\\usepackage.*{ctex}",
        r"\\usepackage.*{xeCJK}",
        r"\\documentclass.*{ctexart}",
        r"\\documentclass.*{ctexbook}",
        r"\\documentclass.*{ctexrep}",
        r"\\documentclass.*{thuthesis}",
        r"\\documentclass.*{pkuthss}",
        r"\\documentclass.*{ustcthesis}",
        r"\\documentclass.*{fduthesis}",
        r"[\u4e00-\u9fff]",  # Chinese characters
    ]

    def __init__(
        self,
        tex_file: str,
        compiler: Optional[str] = None,
        recipe: Optional[str] = None,
        shell_escape: bool = False,
    ):
        self.tex_file = Path(tex_file).resolve()
        self.work_dir = self.tex_file.parent
        self.compiler = compiler or self._detect_compiler()
        self.recipe = recipe
        self.shell_escape = shell_escape

    def _detect_compiler(self) -> str:
        """Auto-detect appropriate compiler based on document content."""
        try:
            content = self.tex_file.read_text(encoding="utf-8", errors="ignore")
        except Exception:
            return "pdflatex"  # Default fallback

        # Check for Chinese content
        for pattern in self.CHINESE_PATTERNS:
            if re.search(pattern, content):
                print("[INFO] Detected Chinese content, using xelatex")
                return "xelatex"

        # Check for explicit engine specification
        if re.search(r"%\s*!TEX\s+program\s*=\s*xelatex", content, re.IGNORECASE):
            return "xelatex"
        if re.search(r"%\s*!TEX\s+program\s*=\s*lualatex", content, re.IGNORECASE):
            return "lualatex"
        if re.search(r"%\s*!TEX\s+program\s*=\s*pdflatex", content, re.IGNORECASE):
            return "pdflatex"

        # Check for fontspec (requires xelatex or lualatex)
        if re.search(r"\\usepackage.*{fontspec}", content):
            print("[INFO] Detected fontspec package, using xelatex")
            return "xelatex"

        return "pdflatex"

    def _check_tools_for_compiler(self) -> tuple[bool, str]:
        """Check tools required for latexmk-based compilation."""
        if not shutil.which("latexmk"):
            return False, "latexmk not found — 请先安装"

        compiler_cmd = self.compiler
        if not shutil.which(compiler_cmd):
            return False, f"{compiler_cmd} not found — 请先安装"

        return True, "All tools available"

    def _check_tools_for_recipe(self) -> tuple[bool, str]:
        """Check tools required by a recipe."""
        steps = self.RECIPES.get(self.recipe, [])
        required = []
        for step in steps:
            if step == "latexmk-xelatex":
                required.extend(["latexmk", "xelatex"])
            elif step == "latexmk-lualatex":
                required.extend(["latexmk", "lualatex"])
            elif step in ("xelatex", "lualatex", "bibtex", "biber"):
                required.append(step)

        for tool in dict.fromkeys(required):
            if not shutil.which(tool):
                return False, f"{tool} not found. Install TeX Live or MiKTeX."

        return True, "All tools available"

    def _engine_shell_mode_arg(self) -> str:
        """Return the explicit shell-escape mode passed to TeX engines."""
        return "-shell-escape" if self.shell_escape else "-no-shell-escape"

    def _latexmk_engine_args(self) -> list[str]:
        """Build latexmk engine args with explicit shell-escape mode."""
        if self.compiler not in self.COMPILERS:
            return ["-pdf"]

        engine = self.compiler
        engine = f"{engine} {self._engine_shell_mode_arg()}"

        if self.compiler == "pdflatex":
            return ["-pdf", f"-pdflatex={engine} %O %S"]
        if self.compiler == "xelatex":
            return ["-xelatex", "-pdfxe", f"-xelatex={engine} %O %S"]
        return ["-lualatex", "-pdflua", f"-lualatex={engine} %O %S"]

    def _maybe_warn_shell_escape(self) -> None:
        if self.shell_escape:
            print("[WARNING] Shell escape enabled. Only use with trusted sources.")

    def _log_file(self, outdir: Optional[str] = None) -> Path:
        if outdir:
            return (self.work_dir / outdir / self.tex_file.with_suffix(".log").name).resolve()
        return self.tex_file.with_suffix(".log")

    def _validate_log(self, outdir: Optional[str] = None) -> tuple[bool, list[str]]:
        """Reject PDFs produced from logs that still contain real TeX errors."""
        log_file = self._log_file(outdir)
        if not log_file.exists():
            return False, [f"日志文件不存在: {log_file}"]

        text = log_file.read_text(encoding="utf-8", errors="ignore")
        problems: list[str] = []

        error_lines = []
        for line in text.splitlines():
            if line.startswith("! "):
                # Font warnings are logged as warnings, not bang-errors. Any
                # remaining bang line means TeX recovered after a real error.
                error_lines.append(line.strip())
                if len(error_lines) >= 12:
                    break
        if error_lines:
            problems.append("LaTeX 错误仍存在: " + " | ".join(error_lines))

        failure_patterns = [
            r"Emergency stop",
            r"Fatal error occurred",
            r"Undefined control sequence",
            r"Misplaced alignment tab character",
            r"Missing \$ inserted",
            r"Extra \}, or forgotten",
            r"File `[^']+' not found",
            r"Unable to load picture or PDF file",
            r"Package graphics Error",
        ]
        for pattern in failure_patterns:
            if re.search(pattern, text):
                problems.append(f"日志匹配失败模式: {pattern}")

        unresolved_patterns = [
            r"undefined references",
            r"Citation .* undefined",
            r"Reference .* undefined",
            r"There were undefined references",
            r"Label\(s\) may have changed",
        ]
        for pattern in unresolved_patterns:
            if re.search(pattern, text, re.IGNORECASE):
                problems.append(f"交叉引用/引用未稳定: {pattern}")

        return not problems, problems

    def _report_validation(self, outdir: Optional[str] = None) -> int:
        pdf_file = self.tex_file.with_suffix(".pdf")
        if outdir:
            pdf_file = (self.work_dir / outdir / pdf_file.name).resolve()
        if not pdf_file.exists():
            print(f"\n[ERROR] PDF not found: {pdf_file}")
            return 1

        ok, problems = self._validate_log(outdir)
        if not ok:
            print(f"\n[ERROR] PDF was produced but validation failed: {pdf_file}")
            for problem in problems[:10]:
                print(f"  - {problem}")
            return 1

        print(f"\n[SUCCESS] PDF generated and validated: {pdf_file}")
        return 0

    def compile(
        self, watch: bool = False, biber: bool = False, outdir: Optional[str] = None
    ) -> int:
        """
        Compile the LaTeX document.

        Args:
            watch: Enable continuous compilation mode
            biber: Use biber instead of bibtex
            outdir: Output directory for generated files

        Returns:
            Exit code (0 for success)
        """
        # Check tools
        if self.recipe:
            ok, msg = self._check_tools_for_recipe()
            if not ok:
                print(f"[ERROR] {msg}")
                return 1
        else:
            ok, msg = self._check_tools_for_compiler()
            if not ok:
                print(f"[ERROR] {msg}")
                return 1

        # If recipe is set, use recipe-based compilation
        if self.recipe:
            return self._compile_with_recipe(outdir)

        print(f"[INFO] Compiling {self.tex_file.name} with {self.compiler}")
        print(f"[INFO] Working directory: {self.work_dir}")
        self._maybe_warn_shell_escape()

        # Build latexmk command
        cmd = ["latexmk"]

        # Add compiler-specific options
        cmd.extend(self._latexmk_engine_args())

        # Add common options
        cmd.extend(
            [
                "-interaction=nonstopmode",
                "-file-line-error",
                "-synctex=1",
            ]
        )

        # Biber support
        if biber:
            cmd.append("-use-biber")

        # Watch mode
        if watch:
            cmd.append("-pvc")
            print("[INFO] Watch mode enabled. Press Ctrl+C to stop.")

        # Add input file
        cmd.append(str(self.tex_file))

        # Run compilation
        try:
            result = subprocess.run(
                cmd,
                cwd=self.work_dir,
                capture_output=False,
            )
            if result.returncode == 0:
                return self._report_validation(outdir)
            else:
                print(f"\n[ERROR] Compilation failed with exit code {result.returncode}")
            return result.returncode

        except KeyboardInterrupt:
            print("\n[INFO] Compilation stopped by user")
            return 0
        except Exception as e:
            print(f"[ERROR] {e}")
            return 1

    def _compile_with_recipe(self, outdir: Optional[str] = None) -> int:
        """Compile using a predefined recipe (VS Code LaTeX Workshop style)."""
        if self.recipe not in self.RECIPES:
            print(f"[ERROR] Unknown recipe: {self.recipe}")
            print(f"[INFO] Available recipes: {', '.join(self.RECIPES.keys())}")
            return 1

        steps = self.RECIPES[self.recipe]
        print(f"[INFO] Using recipe: {self.recipe}")
        print(f"[INFO] Steps: {' -> '.join(steps)}")
        print(f"[INFO] Working directory: {self.work_dir}")
        self._maybe_warn_shell_escape()

        tex_base = self.tex_file.stem

        for i, step in enumerate(steps, 1):
            print(f"\n[STEP {i}/{len(steps)}] Running {step}...")

            if step == "latexmk-xelatex":
                cmd = [
                    "latexmk",
                    "-xelatex",
                    f"-xelatex=xelatex {self._engine_shell_mode_arg()} %O %S",
                    "-interaction=nonstopmode",
                    "-synctex=1",
                    "-file-line-error",
                ]
                if outdir:
                    cmd.append(f"-outdir={outdir}")
                cmd.append(str(self.tex_file))
            elif step == "latexmk-lualatex":
                cmd = [
                    "latexmk",
                    "-lualatex",
                    f"-lualatex=lualatex {self._engine_shell_mode_arg()} %O %S",
                    "-interaction=nonstopmode",
                    "-synctex=1",
                    "-file-line-error",
                ]
                if outdir:
                    cmd.append(f"-outdir={outdir}")
                cmd.append(str(self.tex_file))
            elif step in ("xelatex", "lualatex"):
                cmd = [
                    step,
                    "-interaction=nonstopmode",
                    "-synctex=1",
                    self._engine_shell_mode_arg(),
                    str(self.tex_file),
                ]
            elif step == "bibtex":
                cmd = ["bibtex", tex_base]
            elif step == "biber":
                cmd = ["biber", tex_base]
            else:
                print(f"[ERROR] Unknown step: {step}")
                return 1

            try:
                result = subprocess.run(
                    cmd,
                    cwd=self.work_dir,
                    capture_output=False,
                )
                if result.returncode != 0:
                    # bibtex/biber may return non-zero for warnings, continue anyway
                    if step not in ("bibtex", "biber"):
                        print(f"[ERROR] Step {step} failed with exit code {result.returncode}")
                        return result.returncode
                    else:
                        print(f"[WARNING] {step} returned {result.returncode}, continuing...")

            except FileNotFoundError:
                print(f"[ERROR] {step} not found. Please install it.")
                return 1
            except Exception as e:
                print(f"[ERROR] {e}")
                return 1

        return self._report_validation(outdir)

    @staticmethod
    def _detect_os_info() -> dict:
        """Detect OS and package manager for install hints."""
        system = platform.system()
        if system == "Linux":
            # Check for specific distro
            try:
                import distro as distro_pkg
                distro_id = distro_pkg.id()
            except ImportError:
                distro_id = ""
            # Fallback: check known package managers
            if shutil.which("apt"):
                return {"os": "linux-deb", "pkg": "apt", "cmd": "sudo apt-get install -y", "prefix": ""}
            elif shutil.which("pacman"):
                return {"os": "linux-arch", "pkg": "pacman", "cmd": "sudo pacman -S --noconfirm", "prefix": ""}
            elif shutil.which("dnf"):
                return {"os": "linux-rpm", "pkg": "dnf", "cmd": "sudo dnf install -y", "prefix": "texlive-"}
            elif shutil.which("yum"):
                return {"os": "linux-rpm", "pkg": "yum", "cmd": "sudo yum install -y", "prefix": "texlive-"}
            elif shutil.which("zypper"):
                return {"os": "linux-suse", "pkg": "zypper", "cmd": "sudo zypper install -y", "prefix": "texlive-"}
            else:
                return {"os": "linux", "pkg": "unknown", "cmd": "", "prefix": ""}
        elif system == "Darwin":
            return {"os": "macos", "pkg": "brew", "cmd": "brew install", "prefix": ""}
        elif system == "Windows":
            return {"os": "windows", "pkg": "winget", "cmd": "winget install", "prefix": ""}
        else:
            return {"os": "unknown", "pkg": "unknown", "cmd": "", "prefix": ""}

    @classmethod
    def _check_chinese_fonts(cls) -> dict:
        """Check availability of common Chinese fonts.

        Returns:
            dict: {family_name: {"available": bool, "sample": str}}
        """
        RECOMMENDED = [
            "Noto Serif CJK SC", "Noto Sans CJK SC",
            "Source Han Serif SC", "Source Han Sans SC",
            "WenQuanYi Micro Hei", "WenQuanYi Zen Hei",
            "SimSun", "SimHei", "KaiTi", "FangSong",
            "AR PL UMing CN", "AR PL UKai CN",
        ]
        found = {f: {"available": False, "sample": ""} for f in RECOMMENDED}

        # Try fc-list first (standard on Linux/macOS with fontconfig)
        try:
            result = subprocess.run(
                ["fc-list", ":lang=zh", "family"], capture_output=True, text=True, timeout=10
            )
            if result.returncode == 0:
                for line in result.stdout.splitlines():
                    family = line.strip().rstrip(',')
                    for name in RECOMMENDED:
                        if name in family:
                            found[name]["available"] = True
                            found[name]["sample"] = family[:80]
        except (FileNotFoundError, subprocess.TimeoutExpired):
            pass

        # Fallback: check known font file paths
        for name in RECOMMENDED:
            if not found[name]["available"]:
                pass  # glob check skipped — fc-list is definitive enough

        return found

    @classmethod
    def check_tools(cls) -> dict:
        """Check availability of all compilation tools and Chinese fonts.

        Does NOT hardcode package names — caller should web-search for the
        correct install command on the detected distro.

        Returns:
            dict with keys: os_info, tools, fonts, missing
        """
        os_info = cls._detect_os_info()

        tools = {
            "xelatex": "xelatex", "xetex": "xetex",
            "lualatex": "lualatex", "luatex": "luatex",
            "pdflatex": "pdflatex", "latexmk": "latexmk",
            "bibtex": "bibtex", "biber": "biber",
        }
        results = {}
        for name, cmd in tools.items():
            path = shutil.which(cmd)
            results[name] = {"available": path is not None, "path": path or ""}

        # Chinese font detection
        fonts = cls._check_chinese_fonts()

        # Print report
        pkg_name = os_info["pkg"].upper()
        print("\n" + "=" * 55)
        print(f"  LaTeX 编译工具链检测  [{os_info['os']}/{pkg_name}]")
        print("=" * 55)
        print("  --- 编译引擎 ---")
        missing = []
        engine_names = ["xelatex", "xetex", "lualatex", "luatex", "pdflatex"]
        for name in engine_names:
            info = results[name]
            if info["available"]:
                print(f"  [OK]  {name:<12}  {info['path']}")
            else:
                print(f"  [MISS] {name:<12}  (请 web 搜索安装方式)")
                missing.append(name)
        print("  --- 构建工具 ---")
        for name in ["latexmk", "bibtex", "biber"]:
            info = results[name]
            if info["available"]:
                print(f"  [OK]  {name:<12}  {info['path']}")
            else:
                print(f"  [MISS] {name:<12}  (请 web 搜索安装方式)")
                missing.append(name)
        print("  --- 中文字体（推荐） ---")
        font_missing = []
        for fname, finfo in fonts.items():
            if finfo["available"]:
                print(f"  [OK]  {fname:<24}")
            else:
                font_missing.append(fname)
        if font_missing:
            print(f"  缺失推荐字体: {', '.join(font_missing)}")
            print(f"  (至少需要一种中文字体用于编译)")
        print("-" * 55)
        print(f"  编译工具: {sum(1 for n in tools if results[n]['available'])}/{len(tools)}")
        print(f"  中文字体: {sum(1 for f in fonts.values() if f['available'])}/{len(fonts)}")
        print("=" * 55)

        # Output structured JSON
        report = {
            "os": os_info["os"],
            "package_manager": os_info["pkg"],
            "tools": results,
            "fonts": {k: v["available"] for k, v in fonts.items()},
            "missing_tools": missing,
            "missing_fonts": font_missing,
            "search_query": f"install {' '.join(missing)} on {platform.system()} {os_info['pkg']}",
        }
        print("\n[TOOLS_JSON] " + json.dumps(report, ensure_ascii=False) + "\n")
        return report

    def clean(self, full: bool = False) -> int:
        """
        Clean auxiliary files.

        Args:
            full: Also remove output PDF

        Returns:
            Exit code (0 for success)
        """
        print(f"[INFO] Cleaning auxiliary files in {self.work_dir}")

        cmd = ["latexmk", "-c"]
        if full:
            cmd = ["latexmk", "-C"]

        cmd.append(str(self.tex_file))

        try:
            result = subprocess.run(cmd, cwd=self.work_dir, capture_output=True)
            if result.returncode == 0:
                print("[SUCCESS] Auxiliary files cleaned")
            return result.returncode
        except Exception as e:
            print(f"[ERROR] {e}")
            return 1


def main():
    parser = argparse.ArgumentParser(
        description="LaTeX 中文学位论文编译脚本 - 支持 xelatex/lualatex",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
默认行为:
  使用 latexmk + XeLaTeX 自动处理所有依赖（bibtex/biber、交叉引用等），
  并自动决定最优编译次数。这是中文论文的推荐方案。

Recipes (中文论文推荐 XeLaTeX):
  latexmk          LaTeXmk + XeLaTeX 自动处理 (默认 - 推荐)
  xelatex          XeLaTeX 单次编译
  lualatex         LuaLaTeX 单次编译
  xelatex-bibtex   xelatex -> bibtex -> xelatex*2 (传统 BibTeX)
  xelatex-biber    xelatex -> biber -> xelatex*2 (现代 biblatex)
  lualatex-bibtex  lualatex -> bibtex -> lualatex*2
  lualatex-biber   lualatex -> biber -> lualatex*2

Examples:
  uv run python compile.py main.tex                        # 默认: latexmk + xelatex
  uv run python compile.py main.tex --recipe xelatex-bibtex  # 传统 BibTeX
  uv run python compile.py main.tex --recipe xelatex-biber   # 现代 biblatex
  uv run python compile.py main.tex --watch                # 监视模式
        """,
    )
    parser.add_argument("tex_file", nargs="?", help="主 .tex 文件路径 (--check-tools 时可选)")
    parser.add_argument("-d", "--dir", dest="work_dir_arg", help="包含主 .tex 的目录（兼容 AGENTS.md 常用命令）")
    parser.add_argument("--main", default="main.tex", help="-d/--dir 模式下的主 .tex 文件名，默认 main.tex")
    parser.add_argument(
        "--compiler",
        "-c",
        choices=["pdflatex", "xelatex", "lualatex"],
        help="编译器 (未指定时自动检测，中文默认 xelatex)",
    )
    parser.add_argument(
        "--recipe",
        "-r",
        choices=[
            "xelatex",
            "lualatex",
            "latexmk",
            "xelatex-bibtex",
            "xelatex-biber",
            "lualatex-bibtex",
            "lualatex-biber",
        ],
        help="使用预定义编译配置 (中文推荐 XeLaTeX)",
    )
    parser.add_argument("--watch", "-w", action="store_true", help="启用监视模式 (持续编译)")
    parser.add_argument("--biber", "-b", action="store_true", help="使用 biber 处理参考文献")
    parser.add_argument(
        "--shell-escape",
        action="store_true",
        help="启用 shell-escape (需要 --trusted-source)",
    )
    parser.add_argument(
        "--trusted-source",
        action="store_true",
        help="确认 LaTeX 源文件可信后再启用 shell-escape",
    )
    parser.add_argument("--clean", action="store_true", help="清理辅助文件")
    parser.add_argument("--clean-all", action="store_true", help="清理所有生成文件 (含 PDF)")
    parser.add_argument("--outdir", "-o", help="输出目录 (仅 latexmk 配置支持)")
    parser.add_argument(
        "--check-tools",
        action="store_true",
        help="检测编译工具链可用性（不编译）",
    )

    args = parser.parse_args()

    # Tool check mode: no tex file needed
    if args.check_tools:
        LaTeXCompiler.check_tools()
        sys.exit(0)

    # Validate input file
    tex_arg = args.tex_file
    if args.work_dir_arg and not tex_arg:
        tex_arg = str(Path(args.work_dir_arg) / args.main)
    if not tex_arg:
        parser.error("需要提供 tex_file，或使用 -d/--dir 指定目录")

    tex_path = Path(tex_arg)
    if not tex_path.exists():
        print(f"[ERROR] 文件不存在: {tex_arg}")
        sys.exit(1)

    if tex_path.suffix != ".tex":
        print(f"[WARNING] 文件扩展名不是 .tex: {args.tex_file}")

    if args.shell_escape and not args.trusted_source:
        print(
            "[ERROR] --shell-escape 可执行 LaTeX 源文件中的命令。"
            "确认源文件可信后再同时传入 --trusted-source。"
        )
        sys.exit(1)

    # Create compiler instance
    compiler = LaTeXCompiler(
        tex_arg,
        args.compiler,
        args.recipe,
        shell_escape=args.shell_escape,
    )

    # Execute requested action
    if args.clean or args.clean_all:
        sys.exit(compiler.clean(full=args.clean_all))
    else:
        sys.exit(
            compiler.compile(
                watch=args.watch,
                biber=args.biber,
                outdir=args.outdir,
            )
        )


if __name__ == "__main__":
    main()

"""
根据中英文字体度量计算最佳行距 (baselineskip)

acmart 模板默认为 \fontsize{10}{12}（ratio = 1.2），这对拉丁文合适，
但中文字符笔划密度大，需要更大行距。此脚本通过解析实际字体度量
（hhea/OS2 表）量化视觉差异，输出推荐的 \fontsize{size}{skip} 配置。

Usage:
    uv run python compute_baselineskip.py main.tex
    uv run python compute_baselineskip.py main.tex --json
    uv run python compute_baselineskip.py main.tex --cjk "Noto Serif CJK SC"
    uv run python compute_baselineskip.py main.tex --cjk-scale 1.1
    uv run python compute_baselineskip.py main.tex --cjk-scale 1.1 --code-only
"""

import argparse
import json
import re
import struct
import subprocess
import sys
from pathlib import Path


# ──────────────────────────── Font Metadata ────────────────────────────

# Standard CJK line spacing factor (Latin default = 1.2, CJK needs 1.3-1.5)
DEFAULT_CJK_FACTOR = 1.35

# For font sizes not explicitly listed in acmart.cls, interpolate
FONT_SIZE_BASELINE = {
    # acmart.cls \ACM@fontsize{size}{baselineskip} definitions
    7: (7, 8),         # \@acmtiny
    8: (8, 10),        # \@acmsmall
    9: (9, 11),        # interpolated (~1.22 ratio)
    10: (10, 12),      # \@acmnormal
    11: (11, 13),      # interpolated (~1.18 ratio)
    12: (12, 14),      # interpolated (~1.17 ratio)
}


def read_font_metrics(font_path: str, ttc_index: int = 0) -> dict:
    """
    从字体二进制文件中读取 hhea 和 OS/2 表的度量数据。

    支持 .otf/.ttf 和 .ttc 格式。返回 dict:
        upem: 单位 em 大小（通常 1000）
        ascender: hhea 表 ascender (font units)
        descender: hhea 表 descender（通常为负值）
        linegap: hhea 表 lineGap
        typo_ascender: OS/2 sTypoAscender
        typo_descender: OS/2 sTypoDescender（通常为负值）
        typo_linegap: OS/2 sTypoLineGap
    """
    with open(font_path, 'rb') as f:
        header = f.read(4)
        base_offset = 0
        if header == b'ttcf':
            _, num_fonts = struct.unpack('>II', f.read(8))
            if ttc_index >= num_fonts:
                raise ValueError(f"TTC index {ttc_index} out of range (0-{num_fonts - 1})")
            f.read(ttc_index * 4)
            base_offset = struct.unpack('>I', f.read(4))[0]
            f.seek(base_offset)
            _ = f.read(4)  # sfVersion

        # Table directory starts at base_offset + 4
        f.seek(base_offset + 4)
        num_tables, _, _, _ = struct.unpack('>HHHH', f.read(8))

        tables = {}
        for _ in range(num_tables):
            tag, _, off, length = struct.unpack('>4sIII', f.read(16))
            tables[tag] = (off, length)

        def get_table(tag: bytes):
            if tag not in tables:
                return None
            off, length = tables[tag]
            f.seek(off)
            return f.read(length)

        head = get_table(b'head')
        hhea = get_table(b'hhea')
        os2 = get_table(b'OS/2')

        upem = struct.unpack('>H', head[18:20])[0] if head and len(head) >= 20 else 1000
        ascender = struct.unpack('>h', hhea[4:6])[0] if hhea and len(hhea) >= 6 else 0
        descender = struct.unpack('>h', hhea[6:8])[0] if hhea and len(hhea) >= 8 else 0
        linegap = struct.unpack('>h', hhea[8:10])[0] if hhea and len(hhea) >= 10 else 0

        ta = struct.unpack('>h', os2[68:70])[0] if os2 and len(os2) >= 70 else ascender
        td = struct.unpack('>h', os2[70:72])[0] if os2 and len(os2) >= 72 else descender
        tl = struct.unpack('>h', os2[72:74])[0] if os2 and len(os2) >= 74 else linegap

        return {
            'upem': upem,
            'ascender': ascender,
            'descender': descender,
            'linegap': linegap,
            'typo_ascender': ta,
            'typo_descender': td,
            'typo_linegap': tl,
        }


def find_font_file(font_name: str) -> str | None:
    """通过 fc-match 查找字体文件路径。"""
    try:
        result = subprocess.run(
            ['fc-match', '-v', font_name],
            capture_output=True, text=True, timeout=10,
        )
        if result.returncode != 0:
            return None
        for line in result.stdout.splitlines():
            m = re.match(r'\s*file:\s*"(.+?)"\s*', line)
            if m:
                return m.group(1)
    except (FileNotFoundError, subprocess.TimeoutExpired):
        pass
    return None


# ──────────────────────────── LaTeX Parsing ────────────────────────────

def parse_font_size_from_tex(main_tex: str) -> int:
    r"""从 \documentclass[...,<size>pt,...]{...} 提取基础字号。"""
    with open(main_tex, 'r') as f:
        content = f.read()

    m = re.search(
        r'\\documentclass\s*\[([^\]]*?)\]\s*\{',
        content, re.DOTALL,
    )
    if m:
        options = m.group(1)
        size_m = re.search(r'(\d+)\s*pt', options)
        if size_m:
            return int(size_m.group(1))

    # acmart default is 10pt
    doc_m = re.search(r'\\documentclass\s*\{(\w+)\}', content)
    if doc_m and doc_m.group(1) == 'acmart':
        return 10

    return 10


def parse_cjk_font_from_tex(main_tex: str) -> str | None:
    r"""从 \setCJKmainfont{<name>} 提取 CJK 主字体名。"""
    with open(main_tex, 'r') as f:
        content = f.read()

    m = re.search(r'\\setCJKmainfont\s*\{([^}]+)\}', content)
    if m:
        return m.group(1).strip()
    return None


def parse_cls_baselineskip(main_tex: str) -> float | None:
    """从关联的 .cls 文件中查找 \fontsize 定义获取原始行距。"""
    with open(main_tex, 'r') as f:
        content = f.read()
    m = re.search(r'\\documentclass\s*(?:\[[^\]]*\])?\s*\{(\w+)\}', content)
    if not m:
        return None
    cls_name = m.group(1)
    tex_dir = Path(main_tex).parent

    cls_path = tex_dir / f"{cls_name}.cls"
    if not cls_path.exists():
        cls_path = Path(f"{cls_name}.cls")

    if not cls_path.exists():
        try:
            result = subprocess.run(
                ['kpsewhich', f'{cls_name}.cls'],
                capture_output=True, text=True, timeout=10,
            )
            if result.returncode == 0:
                cls_path = Path(result.stdout.strip())
        except Exception:
            pass

    if not cls_path.exists():
        return None

    with open(cls_path, 'r', errors='ignore') as f:
        cls_content = f.read()

    patterns = [
        r'\\@acmnormal\s*\{(.*?)\}',
        r'\\fontsize\s*\{(\d+)\}\s*\{(\d+)\}',
        r'\\newcommand\s*\{\\@acmnormal\}\s*\{[^}]*\\fontsize\s*\{(\d+)\}\s*\{(\d+)\}',
    ]
    for pat in patterns:
        m = re.search(pat, cls_content, re.DOTALL)
        if m:
            groups = m.groups()
            if len(groups) == 1:
                inner_m = re.search(r'\\fontsize\s*\{(\d+)\}\s*\{(\d+)\}', groups[0])
                if inner_m:
                    return float(inner_m.group(2))
            elif len(groups) == 2:
                return float(groups[1])

    return None


# ──────────────────────────── Core Calculation ────────────────────────────

def compute_baselineskip(
    font_size: int,
    latin_font: str | None = None,
    cjk_font: str | None = None,
    cjk_scale: float = 1.0,
) -> dict:
    """
    计算最佳行距。

    参数:
        font_size:  基础拉丁文字号（pt）
        cjk_scale:  中文字体缩放因子（`\\setCJKmainfont{...}[Scale=<cjk_scale>]`）
                    计算行距时会基于缩放后的实际字号。
    公式:
        cjk_eff_ratio = min(cjk_typo_body / cjk_upem, 1.0)
        cjk_factor = latin_factor * (1 + (1.0 - cjk_eff_ratio) * 0.5 + 0.12)
        # 当 CJK visual body 少于 em-square 时，说明字体内部空隙少、密度大
        # 需要增加行距；+0.12 是基准中文行距增量
        baselineskip = effective_size * cjk_factor

    回退策略:
        若无法读取字体度量 → 使用 DEFAULT_CJK_FACTOR = 1.35
    """
    # 计算 CJK 实际显示字号
    effective_size = font_size * cjk_scale

    # 1. 获取拉丁文默认行距因子
    latin_size, latin_skip = FONT_SIZE_BASELINE.get(
        font_size, (font_size, int(font_size * 1.2))
    )
    latin_factor = latin_skip / latin_size

    # 2. 获取 CJK 字体度量
    cjk_metrics = None
    cjk_path = None
    if cjk_font:
        cjk_path = find_font_file(cjk_font)
    if not cjk_path:
        cjk_path = find_font_file('Noto Serif CJK SC')

    if cjk_path:
        try:
            cjk_metrics = read_font_metrics(cjk_path)
        except Exception:
            pass

    # 3. 计算 CJK 视觉密度因子
    if cjk_metrics and cjk_metrics['upem'] > 0:
        cjk_body = cjk_metrics['typo_ascender'] + abs(cjk_metrics['typo_descender'])
        cjk_body_ratio = cjk_body / cjk_metrics['upem']
        # CJK typo body 通常等于 em (ratio=1.0)，但实际字符视觉密度更大
        # density = 1 - ratio: ratio 越小说明字体内空白越多，越不需要增加行距
        density = max(0.0, 1.0 - cjk_body_ratio)
        cjk_factor = latin_factor + density * 0.5 + 0.12
    else:
        cjk_factor = DEFAULT_CJK_FACTOR

    # 4. 计算并夹取行距（基于 CJK 实际显示字号）
    baselineskip = effective_size * cjk_factor
    baselineskip = max(baselineskip, latin_skip * 1.04)       # 不低于拉丁行距的 104%
    baselineskip = min(baselineskip, effective_size * 1.6)    # 不超过 CJK 字号的 1.6 倍
    baselineskip = round(baselineskip * 2) / 2  # 舍入到 0.5pt

    # 5. 拉丁字体信息（诊断用）
    latin_metrics = None
    latin_path = None
    if latin_font:
        latin_path = find_font_file(latin_font)
    if not latin_path:
        for name in ['Linux Libertine O', 'LinLibertine', 'Libertine',
                      'Latin Modern Roman', 'Noto Serif']:
            latin_path = find_font_file(name)
            if latin_path:
                break

    if latin_path:
        try:
            latin_metrics = read_font_metrics(latin_path)
        except Exception:
            pass

    return {
        'font_size': font_size,
        'cjk_scale': cjk_scale,
        'effective_size': effective_size,
        'original_baselineskip': latin_skip,
        'original_factor': round(latin_factor, 4),
        'cjk_factor': round(cjk_factor, 4),
        'recommended_baselineskip': baselineskip,
        'cjk_font': cjk_font,
        'cjk_path': cjk_path,
        'cjk_metrics': cjk_metrics,
        'latin_font_name': 'Linux Libertine O' if not latin_font else latin_font,
        'latin_path': latin_path,
        'latin_metrics': latin_metrics,
    }


def format_result(result: dict, json_mode: bool = False, code_only: bool = False) -> str:
    """格式化输出结果。"""
    if json_mode:
        output = {
            'font_size': result['font_size'],
            'cjk_scale': result['cjk_scale'],
            'effective_size': result['effective_size'],
            'baselineskip': result['recommended_baselineskip'],
            'factor': result['cjk_factor'],
            'original_baselineskip': result['original_baselineskip'],
            'cjk_font': result['cjk_font'],
        }
        return json.dumps(output, ensure_ascii=False)

    lines = []
    lines.append(f"基础字号:          {result['font_size']}pt")
    if result['cjk_scale'] != 1.0:
        lines.append(f"CJK 缩放:           {result['cjk_scale']} "
                     f"(实际字号 {result['effective_size']}pt)")
    lines.append(f"原始拉丁行距:       {result['original_baselineskip']}pt "
                 f"(因子 {result['original_factor']})")
    if result['cjk_metrics']:
        m = result['cjk_metrics']
        body = m['typo_ascender'] + abs(m['typo_descender'])
        cjk_label = result['cjk_font'] or '(自动检测)'
        lines.append(f"CJK 字体度量:       {cjk_label}")
        lines.append(f"  upem={m['upem']}  typo_body={body} "
                     f"({m['typo_ascender']}/{-abs(m['typo_descender'])})")
    else:
        cjk_label = result['cjk_font'] or '(未指定，使用默认因子)'
        lines.append(f"CJK 字体:          {cjk_label}")
    if result['latin_metrics']:
        m = result['latin_metrics']
        body = m['typo_ascender'] + abs(m['typo_descender'])
        lines.append(f"拉丁字体度量:       {result['latin_font_name']}")
        lines.append(f"  upem={m['upem']}  typo_body={body} "
                     f"({m['typo_ascender']}/{-abs(m['typo_descender'])})")
    lines.append(f"CJK 行距因子:       {result['cjk_factor']}")
    lines.append(f"\n推荐行距:           {result['recommended_baselineskip']}pt")

    if code_only:
        cjk_font = result.get('cjk_font')
        if cjk_font and result['cjk_scale'] != 1.0:
            return (f"\\setCJKmainfont{{{cjk_font}}}[Scale={{{result['cjk_scale']}}}]\n"
                    f"\\fontsize{{{result['font_size']}}}"
                    f"{{{result['recommended_baselineskip']}}}\\selectfont")
        return (f"\\fontsize{{{result['font_size']}}}"
                f"{{{result['recommended_baselineskip']}}}\\selectfont")

    if cjk_font := result.get('cjk_font'):
        if result['cjk_scale'] != 1.0:
            lines.append(f"\nLaTeX 代码:\n  "
                         f"\\setCJKmainfont{{{cjk_font}}}[Scale={{{result['cjk_scale']}}}]\n  "
                         f"\\fontsize{{{result['font_size']}}}"
                         f"{{{result['recommended_baselineskip']}}}\\selectfont")
        else:
            lines.append(f"\nLaTeX 代码:\n  "
                         f"\\fontsize{{{result['font_size']}}}"
                         f"{{{result['recommended_baselineskip']}}}\\selectfont")
    else:
        lines.append(f"\nLaTeX 代码:\n  "
                     f"\\fontsize{{{result['font_size']}}}"
                     f"{{{result['recommended_baselineskip']}}}\\selectfont")
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="根据中英文字体度量计算最佳行距 (baselineskip)",
    )
    parser.add_argument(
        'main_tex', nargs='?',
        help='主 .tex 文件路径',
    )
    parser.add_argument(
        '--cjk', '--cjk-font', dest='cjk_font',
        help='CJK 主字体名称（如 "Noto Serif CJK SC"）',
    )
    parser.add_argument(
        '--latin', '--latin-font', dest='latin_font',
        help='拉丁字体名称（如 "Linux Libertine O"）',
    )
    parser.add_argument(
        '--json', action='store_true',
        help='以 JSON 格式输出',
    )
    parser.add_argument(
        '--font-size', '-s', type=int, default=None,
        help='显式指定基础字号 (pt)，不指定则从 .tex 文件解析',
    )
    parser.add_argument(
        '--cjk-scale', type=float, default=1.0,
        help='CJK 字体缩放因子（\\setCJKmainfont{...}[Scale=<val>]，默认 1.0）',
    )
    parser.add_argument(
        '--code-only', action='store_true',
        help='仅输出 LaTeX 代码行，供 pipeline 使用',
    )

    args = parser.parse_args()

    font_size = args.font_size

    if args.main_tex:
        tex_path = Path(args.main_tex)
        if not tex_path.exists():
            print(f"[ERROR] 文件不存在: {args.main_tex}", file=sys.stderr)
            sys.exit(1)
        if font_size is None:
            font_size = parse_font_size_from_tex(str(tex_path))
        if args.cjk_font is None:
            cjk_font = parse_cjk_font_from_tex(str(tex_path))
        else:
            cjk_font = args.cjk_font
    else:
        if font_size is None:
            font_size = 10
        cjk_font = args.cjk_font

    result = compute_baselineskip(
        font_size=font_size,
        latin_font=args.latin_font,
        cjk_font=cjk_font,
        cjk_scale=args.cjk_scale,
    )
    print(format_result(result, json_mode=args.json, code_only=args.code_only))


if __name__ == '__main__':
    main()