latex-vscode

name	latex-vscode
description	一键配置 LaTeX + VS Code 本地编写环境。当用户要求配置 LaTeX、安装 LaTeX Workshop、从 Overleaf 迁移到本地、或提到 pdflatex/xelatex/latexmk/MacTeX 时触发此 skill。会自动检测环境、安装插件、写入配置、验证可用。

LaTeX + VS Code 本地环境一键配置

当此 skill 被触发时，按以下步骤自动为用户配置环境。每完成一步输出结果，遇到问题时停下来问用户。

---

Step 1: 检测环境

运行以下检查，输出结果摘要：

echo "=== OS ==="
uname -s

echo "=== LaTeX 引擎 ==="
if command -v pdflatex &>/dev/null; then
  echo "INSTALLED: $(pdflatex --version | head -1)"
else
  echo "NOT_INSTALLED"
fi

echo "=== XeLaTeX ==="
if command -v xelatex &>/dev/null; then
  echo "INSTALLED: $(xelatex --version | head -1)"
else
  echo "NOT_INSTALLED"
fi

echo "=== VS Code CLI ==="
if command -v code &>/dev/null; then
  echo "INSTALLED: $(code --version | head -1)"
else
  echo "NOT_INSTALLED"
fi

echo "=== LaTeX Workshop 插件 ==="
if code --list-extensions 2>/dev/null | grep -qi "james-yu.latex-workshop"; then
  echo "INSTALLED"
else
  echo "NOT_INSTALLED"
fi

如果 pdflatex NOT_INSTALLED： 告诉用户需要先安装 LaTeX 引擎，根据 OS 给出指引：

• macOS: brew install --cask mactex 或从 https://tug.org/mactex/mactex-download.html 下载 (~6GB)
• Linux: sudo apt install texlive-full 或 sudo dnf install texlive-scheme-full
• Windows: 从 https://miktex.org/ 下载 MiKTeX

安装后需要重启终端，然后重新运行此 skill。STOP，不要继续后续步骤。

如果 code NOT_INSTALLED： 告诉用户需要先安装 VS Code，并在 VS Code 中通过 Command Palette 运行 "Shell Command: Install 'code' command in PATH"。STOP。

如果都已安装： 继续下一步。

---

Step 2: 安装 VS Code 插件

code --install-extension James-Yu.latex-workshop --force

可选插件（问用户是否需要）：

code --install-extension yzane.markdown-pdf --force        # Markdown 转 PDF
code --install-extension torn4dom4n.latex-support --force   # LaTeX 语法支持增强

Ultra Math Preview 插件（公式悬停预览）：

code --install-extension yfzhao.ultra-math-preview --force

---

Step 3: 写入 settings.json 配置

读取用户当前的 VS Code settings.json：

SETTINGS_FILE="$HOME/Library/Application Support/Code/User/settings.json"
# Linux:
# SETTINGS_FILE="$HOME/.config/Code/User/settings.json"
# Windows:
# SETTINGS_FILE="$APPDATA/Code/User/settings.json"

if [ -f "$SETTINGS_FILE" ]; then
  echo "FOUND: $SETTINGS_FILE"
else
  echo "NOT_FOUND — will create"
fi

用 Read 工具读取现有 settings.json（如果存在），然后用 Edit 工具合并以下配置（不要覆盖用户已有的其他设置）：

需要写入的 LaTeX Workshop 配置：

{
  "latex-workshop.latex.autoBuild.run": "never",
  "latex-workshop.showContextMenu": true,
  "latex-workshop.intellisense.package.enabled": true,
  "latex-workshop.message.error.show": false,
  "latex-workshop.message.warning.show": false,
  "latex-workshop.latex.tools": [
    {
      "name": "xelatex",
      "command": "xelatex",
      "args": ["-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOCFILE%"]
    },
    {
      "name": "pdflatex",
      "command": "pdflatex",
      "args": ["-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOCFILE%"]
    },
    {
      "name": "latexmk",
      "command": "latexmk",
      "args": ["-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "-outdir=%OUTDIR%", "%DOCFILE%"]
    },
    {
      "name": "bibtex",
      "command": "bibtex",
      "args": ["%DOCFILE%"]
    }
  ],
  "latex-workshop.latex.recipes": [
    {"name": "XeLaTeX", "tools": ["xelatex"]},
    {"name": "PDFLaTeX", "tools": ["pdflatex"]},
    {"name": "BibTeX", "tools": ["bibtex"]},
    {"name": "LaTeXmk", "tools": ["latexmk"]},
    {"name": "xelatex -> bibtex -> xelatex*2", "tools": ["xelatex", "bibtex", "xelatex", "xelatex"]},
    {"name": "pdflatex -> bibtex -> pdflatex*2", "tools": ["pdflatex", "bibtex", "pdflatex", "pdflatex"]}
  ],
  "latex-workshop.latex.clean.fileTypes": [
    "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind", "*.lof", "*.lot", "*.out",
    "*.toc", "*.acn", "*.acr", "*.alg", "*.glg", "*.glo", "*.gls", "*.ist",
    "*.fls", "*.log", "*.fdb_latexmk", "*.synctex.gz", "*.bcf", "*.run.xml",
    "*.nav", "*.snm", "*.vrb"
  ],
  "latex-workshop.latex.autoClean.run": "onBuilt",
  "latex-workshop.latex.recipe.default": "lastUsed",
  "latex-workshop.view.pdf.internal.synctex.keybinding": "double-click",
  "editor.unicodeHighlight.allowedLocales": {"zh-hans": true, "zh-hant": true},
  "[latex]": {"editor.defaultFormatter": "James-Yu.latex-workshop"}
}

---

Step 4: 验证环境

在当前目录创建一个测试文件并编译：

cat > /tmp/latex-test.tex << 'EOF'
\documentclass{article}
\usepackage[utf8]{inputenc}
\title{LaTeX Environment Test}
\author{Test}
\date{\today}
\begin{document}
\maketitle
\section{Hello}
LaTeX is working! Formula test: $E = mc^2$
\end{document}
EOF

cd /tmp && pdflatex -interaction=nonstopmode latex-test.tex

检查结果：

• 如果生成了 latex-test.pdf → 输出 "LaTeX 环境配置成功！"
• 如果编译失败 → 输出错误信息，帮用户排查

清理测试文件：

rm -f /tmp/latex-test.tex /tmp/latex-test.pdf /tmp/latex-test.aux /tmp/latex-test.log

---

Step 5: 输出使用指南

配置完成后，告诉用户：

1. 编译方式：打开 .tex 文件后，用 Ctrl+Alt+B (Mac: Cmd+Option+B) 编译
2. 选择编译配方：Ctrl+Shift+P → 输入 "LaTeX Workshop: Build with recipe"
3. 预览 PDF：Ctrl+Alt+V (Mac: Cmd+Option+V)

配方	用途
XeLaTeX	中文文档（需配合 \usepackage{ctex}）
PDFLaTeX	英文论文（最常用）
LaTeXmk	自动检测需要编译几次
pdflatex -> bibtex -> pdflatex*2	带参考文献的英文论文
xelatex -> bibtex -> xelatex*2	带参考文献的中文文档

常见问题

• 中文乱码 → 用 XeLaTeX 配方，文档加 \usepackage{ctex}
• 参考文献不显示 → 用带 bibtex 的配方（需多次编译）
• 临时文件多 → 已配置自动清理（autoClean: onBuilt）