Skip to content

brycewang-stanford/Auto-Empirical-Research-Skills / skills/35-bahayonghang-academic-writing-skills/skills/latex-thesis-zh

latex-thesis-zh

Verified

Chinese LaTeX thesis assistant for existing .tex degree thesis projects (XeLaTeX/LuaLaTeX/latexmk). Use this skill whenever a user works on a Chinese master's or doctoral thesis needing compilation, GB/T 7714 bibliography checks, chapter structure mapping, template detection (thuthesis, pkuthss), terminology consistency, logic coherence review, heading lead-in checks, title optimization, de-AI editing, experiment chapter review, three-line table validation, or abstract structure diagnosis. Trigger even for single issues like "帮我编译论文", "检查国标格式", "看看绪论逻辑", "毕业论文", "学位论文", "硕士/博士论文", "三线表", "检查摘要", or "摘要结构".

FileKindSize
SKILL.mdskill md7.8 KB
agents/openai.yamlconfig348 B
evals/evals.jsonconfig7.1 KB
examples/bibliography-and-deai.mdmarkdown525 B
examples/compile-and-template.mdmarkdown463 B
examples/structure-and-consistency.mdmarkdown544 B
references/ABSTRACT_STRUCTURE.mdmarkdown4.9 KB
references/ACADEMIC_STYLE_ZH.mdmarkdown3.8 KB
references/CAPTION_GUIDE.mdmarkdown2.2 KB
references/COMPILATION.mdmarkdown2.0 KB
references/DEAI_GUIDE.mdmarkdown17.8 KB
references/FORBIDDEN_TERMS.mdmarkdown1.3 KB
references/GB_STANDARD.mdmarkdown3.8 KB
references/LOGIC_COHERENCE.mdmarkdown7.4 KB
references/STRUCTURE_GUIDE.mdmarkdown4.2 KB
references/TABLE_GUIDE.mdmarkdown2.6 KB
references/TITLE_OPTIMIZATION.mdmarkdown7.1 KB
references/UNIVERSITIES/generic.mdmarkdown2.1 KB
references/UNIVERSITIES/pku.mdmarkdown1.5 KB
references/UNIVERSITIES/tsinghua.mdmarkdown1.3 KB
references/UNIVERSITIES/yanshan.mdmarkdown1.2 KB
references/WRITING_PHILOSOPHY_ZH.mdmarkdown4.9 KB
references/modules/ABSTRACT.mdmarkdown1.2 KB
references/modules/BIBLIOGRAPHY.mdmarkdown1.3 KB
references/modules/COMPILE.mdmarkdown1.1 KB
references/modules/CONSISTENCY.mdmarkdown2.1 KB
references/modules/DEAI.mdmarkdown1.6 KB
references/modules/EXPERIMENT.mdmarkdown4.9 KB
references/modules/FORMAT.mdmarkdown988 B
references/modules/LOGIC.mdmarkdown2.3 KB
references/modules/TABLES.mdmarkdown1.3 KB
references/modules/TEMPLATE.mdmarkdown1.3 KB
references/modules/TITLE.mdmarkdown1.5 KB
scripts/analyze_abstract.pyscript17.3 KB
scripts/analyze_experiment.pyscript10.3 KB
scripts/analyze_logic.pyscript24.2 KB
scripts/check_consistency.pyscript12.1 KB
scripts/check_format.pyscript7.0 KB
scripts/check_references.pyscript17.6 KB
scripts/check_tables.pyscript16.3 KB
scripts/compile.pyscript15.8 KB
scripts/deai_batch.pyscript10.0 KB
scripts/deai_check.pyscript18.1 KB
scripts/detect_template.pyscript3.7 KB
scripts/generate_table.pyscript8.8 KB
scripts/map_structure.pyscript11.3 KB
scripts/online_bib_verify.pyscript11.9 KB
scripts/optimize_title.pyscript12.5 KB
scripts/parsers.pyscript10.7 KB
scripts/verify_bib.pyscript9.7 KB

scripts/compile.py

View on GitHub
#!/usr/bin/env python3
"""
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 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. Install TeX Live or MiKTeX."

        compiler_cmd = self.compiler
        if not shutil.which(compiler_cmd):
            return False, f"{compiler_cmd} not found. Install TeX Live or MiKTeX."

        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 _latexmk_engine_args(self) -> list[str]:
        """Build latexmk engine args with optional shell-escape."""
        if self.compiler not in self.COMPILERS:
            return ["-pdf"]

        engine = self.compiler
        if self.shell_escape:
            engine = f"{engine} -shell-escape"

        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 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()
        else:
            ok, msg = self._check_tools_for_compiler()
        if not ok:
            print(f"[ERROR] {msg}")
            return 1

        # If recipe is specified, 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("-bibtex")

        # 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:
                pdf_file = self.tex_file.with_suffix(".pdf")
                print(f"\n[SUCCESS] PDF generated: {pdf_file}")
            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",
                    "-interaction=nonstopmode",
                    "-synctex=1",
                    "-file-line-error",
                ]
                if self.shell_escape:
                    cmd.append("-shell-escape")
                if outdir:
                    cmd.append(f"-outdir={outdir}")
                cmd.append(str(self.tex_file))
            elif step == "latexmk-lualatex":
                cmd = [
                    "latexmk",
                    "-lualatex",
                    "-interaction=nonstopmode",
                    "-synctex=1",
                    "-file-line-error",
                ]
                if self.shell_escape:
                    cmd.append("-shell-escape")
                if outdir:
                    cmd.append(f"-outdir={outdir}")
                cmd.append(str(self.tex_file))
            elif step in ("xelatex", "lualatex"):
                cmd = [step, "-interaction=nonstopmode", "-synctex=1", str(self.tex_file)]
                if self.shell_escape:
                    cmd.insert(2, "-shell-escape")
            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

        pdf_file = self.tex_file.with_suffix(".pdf")
        if pdf_file.exists():
            print(f"\n[SUCCESS] PDF generated: {pdf_file}")
            return 0
        else:
            print(f"\n[ERROR] PDF not found: {pdf_file}")
            return 1

    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", help="主 .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 (仅用于可信源)",
    )
    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 配置支持)")

    args = parser.parse_args()

    # Validate input file
    tex_path = Path(args.tex_file)
    if not tex_path.exists():
        print(f"[ERROR] 文件不存在: {args.tex_file}")
        sys.exit(1)

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

    # Create compiler instance
    compiler = LaTeXCompiler(
        args.tex_file,
        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()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall