migrating-latex-templates

LaTeX Proposal Intelligent Migrator

Core Entry Points：python skills/transfer_old_latex_to_new/scripts/run.py --help

One-Click Migration：bash skills/transfer_old_latex_to_new/scripts/migrate.sh --old ... --new ...

Configuration Center：config.yaml

Reference Documentation：references/

Split Documentation： references/quickstart.md / references/config_guide.md / references/api_reference.md / references/troubleshooting.md / references/faq.md / references/case_study_2025_to_2026.md

---

Quick Start

# 一键分析（生成结构差异报告）
python skills/transfer_old_latex_to_new/scripts/run.py analyze \
  --old /path/to/NSFC_2025 \
  --new /path/to/NSFC_2026

# 一键应用（执行迁移，apply前自动快照）
python skills/transfer_old_latex_to_new/scripts/run.py apply \
  --old /path/to/NSFC_2025 \
  --new /path/to/NSFC_2026 \
  --run-id <上一步输出的run_id>

# 一键编译（验证迁移结果）
python skills/transfer_old_latex_to_new/scripts/run.py compile \
  --run-id <run_id> \
  --new /path/to/NSFC_2026

# 一键恢复（回滚到apply前状态）
python skills/transfer_old_latex_to_new/scripts/run.py restore \
  --run-id <run_id> \
  --new /path/to/NSFC_2026

One-Click Migration (Recommended)

bash skills/transfer_old_latex_to_new/scripts/migrate.sh \
  --old /path/to/NSFC_2025 \
  --new /path/to/NSFC_2026

runs Output Isolation (Strongly Recommended: Testing/Batch Processing)

python skills/transfer_old_latex_to_new/scripts/run.py analyze \
  --old /path/to/NSFC_2025 \
  --new /path/to/NSFC_2026 \
  --runs-root /path/to/runs

Output Directory: Default skills/transfer_old_latex_to_new/runs/<run_id>/; specify --runs-root to output to that directory.

runs/<run_id>/
├── input_snapshot/     # 旧新项目输入快照
├── analysis/           # 结构分析JSON（sections_map_*.json, structure_diff.json）
├── plan/               # 迁移计划（migration_plan.json）
├── backup/             # Apply前新项目快照（用于restore）
├── logs/               # 执行日志与编译输出
│   ├── apply_result.json        # 迁移执行结果
│   ├── compile_summary.json     # 编译摘要
│   ├── compile_*_*.out.txt      # 编译标准输出
│   ├── compile_*_*.err.txt      # 编译标准错误
│   └── latex_aux/               # LaTeX 中间文件隔离目录
│       ├── main.aux             # 辅助文件
│       ├── main.log             # 编译日志
│       ├── main.bbl             # BibTeX 输出
│       ├── main.blg             # BibTeX 日志
│       ├── main.out             # hyperref 输出
│       ├── main.toc             # 目录文件
│       └── *.aux                # 其他辅助文件
└── deliverables/       # 交付物（PDF、报告、指南）

Intermediate File Isolation: All LaTeX compilation intermediate files (.aux/.log/.bbl, etc.) are automatically saved in the logs/latex_aux/ directory, avoiding the creation of "junk" files in the project directory. The final PDF is automatically copied back to the project root directory.

---

Preconditions (Iron Rules)

Modification Scope Whitelist

✅ Modifiable:

• extraTex/*.tex content files (Exclude @config.tex）
• New project references/*.bib(if citation format needs updating)
• Artifacts of this skill run:runs/<run_id>/(logs, analysis, backups, deliverables)

❌ Prohibited Modifications:

• main.tex template structure files
• extraTex/@config.tex configuration files
• .cls、.sty style files
• Any system files that affect the compilation environment

More complete process descriptions, configuration, and troubleshooting documentation have been split into references/：

• references/quickstart.md
• references/config_guide.md
• references/api_reference.md
• references/troubleshooting.md

📋 Version and Changes

Current Version: v1.4.0 (synced with config.yaml )

Change Log: See root-level CHANGELOG.md

Optimization Plan: For quality assessment and optimization plan, see plans/v202601081355.md(repository root level)

---

Last Updated: 2026-01-08 Maintainer: Bensz Conan License: MIT