MagicTeX

MagicTeX — 面向 AI Agent 的 LaTeX 编辑器

English · 简体中文 · 日本語 · 한국어 · Español · Français · Deutsch · Português

MagicTeX 是一款为 AI Agent 打造的 LaTeX 编辑器——它是类似 Overleaf 的单窗口工作区，供 Claude Code 使用，由 MCP 服务提供支持，无需本地安装 TeX，也无需 Overleaf 账户：支持实时 PDF 预览、带可视化（所见即所得）模式的源代码编辑器、修改历史，以及可锚定在渲染后 PDF 上、并转化为 Agent 编辑指令的评论。（npm 包：magictex-mcp。）

它使用 WASM TeX Live 2026 引擎（texlyre-busytex）进行编译，该引擎运行在无头浏览器中，因此无需安装占用数 GB 的组件——只需一次性下载 WASM 资源。

安装前先体验

zoelin.dev/tools/magictex 提供了评论 → Agent 工作流的引导式演示，该演示基于真实的工具输出构建。它是一次回放，而非托管实例——TeX 引擎需要一次性下载约 650 MB，Agent 部分则由 Claude 本身提供，因此 MagicTeX 会与你的项目一同运行，而不是运行在网页中。

工作区

一个浏览器窗口（灵感来自 Typst 的单界面编辑器和 LiquidText 的锚定批注）：

┌──────────────────────────────────────────────────────────────┐
│  ✓ up to date · 13 pages        Export .zip · Download PDF   │
├────────────┬──────────────────────────────┬──────────────────┤
│ Source /   │          PDF (live)          │    Comments      │
│ History    │  select text → 💬 comment    │  accepted → ask  │
│  editor,   │  highlights stay anchored    │  Claude to       │
│  timeline  │  auto-reloads on every edit  │  address them    │
│  + diffs   │                              │  → resolved ✓    │
└────────────┴──────────────────────────────┴──────────────────┘

• 批注 → Claude 循环（核心功能）。 像主管批阅打印稿一样审阅渲染后的文档：选中文本，添加批注（“精简这一段”）。然后告诉 Claude “处理我的批注”——它会通过 check_comments 获取带定位的工作项（页码 + 引用段落 + 锚定的源文件 file:line + 你的要求），编辑源文件，并为每张卡片添加说明后将其解决。你与文档交互；Claude 与源文件交互。使用 /loop 即可免手动运行——参见 docs/AGENT-LOOP.md。
• 可编辑源文件面板。 使用 CodeMirror LaTeX 编辑器编辑项目文件——保存（Ctrl+S）会重新编译并刷新 PDF，类似 Typst。也可以继续使用你自己的编辑器：任何保存操作都会触发相同的实时工作流。
• 实时重新加载。 文件监视器会在每次保存时重新编译——无论是 Claude、内置编辑器还是外部编辑器的更改。
• 更改历史。 每次成功编译都会自动创建快照，存入隐藏的 git 引用（refs/latex-preview/checkpoints）——不会触及你的分支、git log 或工作树。历史记录标签页会显示时间线，并在 PDF 旁展示每个检查点的彩色差异。
• 前往 Overleaf。 提供下载 PDF、导出 .zip（干净的构建输入文件包），以及面向公开 GitHub 仓库的一键式在 Overleaf 中打开链接；Premium Git 桥接同步通过文档说明的 git push 完成。参见 docs/USER-GUIDE.md。
• 审阅工作流（审阅者 → 审核关卡 → 解决者）。 审阅者/辩护者 Agent 通过 add_comment 发布批注；你可以接受/拒绝这些批注（或切换自动接受以启用副驾驶模式）；作者循环会解决已接受的批注。批注包含角色和回复串。参见 docs/AGENT-LOOP.md。
• 保存还是重新编译，由你决定。 内置编辑器每 30s 自动保存，但不会重新编译；按 Ctrl+S、点击保存或重新编译即可按需重建 PDF。（切换 ⚡ Live 即可在输入时重新编译。）你自己的编辑器和 Claude 的更改仍会通过文件监视器自动触发重新编译。
• 真实项目。 自动检测主文件，收集多文件 \input/\include、.bib、仓库内的 .cls/.sty/.bst 和插图，运行 BibTeX 并在需要时重新运行；常见缺失宏包会自动注入。
• 编译后端。 如果本机安装了 latexmk，则使用它——完整支持宏包，输出与 Overleaf 一致；否则使用随附的零安装 WASM TeX Live。通过 backend: "system" / "wasm" 可强制指定后端。每次编译都会报告所用的后端。
• 文档类。 内置 IEEEtran，因为 WASM TeX Live 不包含任何会议文档类，而且缺失文档类不像缺失宏包那样可以绕过。会议文档类（NeurIPS、ICML、CVPR、ACL、AAAI …）没有可再分发许可，因此请将作者套件中的 .cls 放在源文件旁；系统会自动识别。
• MCP 工具： render_preview（编译并打开工作区）、check_comments / resolve_comment / add_comment / reply_to_comment（审阅循环）、show_diff（以图像形式并排展示差异——适用于支持图像的客户端）。
• 可采取行动的错误。 编译失败时会返回解析后的 {file, line, message} 错误，供 Claude 自行修正，并在工作区中显示。

设置

MagicTeX 发布在 npm 上，包名为 magictex-mcp，并以 io.github.ZoeLinUTS/magictex 列入 官方 MCP 注册表——因此，任何读取该注册表的客户端都能找到它。无需克隆仓库，也无需安装 TeX；首次使用时，npx 会自动获取它。

1. 将它添加到论文项目的 .mcp.json 中（参见 .mcp.json.example）：

   {
     "mcpServers": {
       "magictex": { "command": "npx", "args": ["-y", "magictex-mcp"] }
     }
   }
   

   如果要从克隆的仓库进行本地开发，请改为指向源文件： "command": "npx", "args": ["tsx", "/absolute/path/to/magictex-mcp/src/server.ts"]

2. 重启 Claude Code（或通过 /mcp 重新连接），以加载该服务。

3. **让 Claude 渲染。**例如："render a preview of this paper" → 首次调用会下载 WASM TeX Live 资源（约 650 MB，仅需下载一次）、进行编译并打开实时预览标签页。之后的编辑会自动重新加载。

WASM 资源不在此仓库中。首次运行时，资源会下载到每位用户各自的缓存目录——macOS 上为 ~/Library/Caches/magictex，Linux 上为 $XDG_CACHE_HOME/magictex，Windows 上为 %LOCALAPPDATA%\magictex——因此升级 MagicTeX 时无需重新下载，并且检出版本、全局安装和 npx 运行共用同一份资源。设置 MAGICTEX_ASSETS_DIR 可将资源存放到其他位置。要预先下载： npx texlyre-busytex download-assets <that directory>。

安装为 Claude Code 插件（斜杠命令）

如果希望减少输入，可以将 MagicTeX 安装为插件——一次安装即可获得 MCP 服务和斜杠命令：

/plugin marketplace add ZoeLinUTS/MagicTeX-mcp
/plugin install magictex

然后，在论文项目中使用工作流命令来完成常见操作：

• /magic-latex — 编译并打开工作区（实时预览）。
• /ai-review [skill] — 使用某项技能审阅论文（默认为 academic-paper-revision；可传入任意技能名称），并发布供你接受或拒绝的评论。找不到技能时，会提示如何安装。
• /address-comments — 处理你已接受的评论（可通过 /loop 60s /address-comments 循环运行）。
• ⚡ /ultra-agents [skill] [depth] — 完全自主运行：审阅、自动接受、修复并重复，最多运行 depth 轮（默认为 2 轮）；一旦某轮未发现新问题，就会提前停止。每轮无需批准——这正是它的设计目的，也是它的风险所在。depth > 5 时，会在开始前要求你确认。运行结束后会提供摘要（提出了哪些问题、做了哪些更改、应检查哪些检查点）——每一轮仍是常规的可撤销检查点。参见 docs/AGENT-LOOP.md。

每个工具对应一个命令

每个 MCP 工具也都有一个同名斜杠命令，因此你只需输入工具名称，即可执行任意单个步骤。要记住的规则是：工具是 X → 输入 /X。

输入此命令	运行的工具	作用
/render_preview	render_preview	编译论文并打开／刷新实时预览。
/check_comments	check_comments	列出你已接受的评论，将其作为编辑说明（尚未进行编辑）。
/resolve_comment [id] [note]	resolve_comment	编辑完成后将评论标记为已处理；评论会变成绿色，供你检查。
/add_comment ["quote"] [note]	add_comment	将评论锚定到一段文字上，供你接受／拒绝。
/reply_to_comment [id] [text]	reply_to_comment	在评论中添加串接回复。
/show_diff [checkpoint]	show_diff	以图片形式并排显示可视化差异（当前更改或某个检查点）。
/list_checkpoints [limit]	list_checkpoints	按时间倒序列出最近的检查点及其 sha——找出一个传给 /show_diff。

你完全不必输入这些命令——用自然语言也可以（例如 “渲染预览”、 “处理我的评论”）。这些命令只是便于教学的快捷方式。

此插件捆绑了 MCP 服务（npx magictex-mcp），因此只需安装插件即可——上方的 .mcp.json 是不想安装插件时的替代方案。无论哪种方式，都可以使用斜杠命令。

工具

面向任何支持 MCP 的客户端的 MCP 接口。（在 Claude Code 中，你可以直接用自然语言提出请求，也可以使用上方的斜杠命令——这些斜杠命令实际调用的就是以下工具。）

工具	参数	作用
render_preview	mainFile? · engine?（pdflatex | xelatex | lualatex，默认 xelatex）· backend?（wasm | system | auto，默认 auto——如果已安装则使用本地 latexmk，否则使用捆绑的 WASM 引擎）	编译项目并打开／刷新实时工作区。如果省略主文件，将通过扫描 \documentclass 自动检测。
check_comments	includeResolved?（默认 false）	返回已接受的评论作为带有位置的待办项——页面、引用片段、源文件 file:line 以及要求。会报告等待你决定的审阅者建议，但不会将其作为待办项返回。
add_comment	quote · comment · role?（reviewer | defender）· page? · accepted?	将评论锚定到一段文字上。除非设置了 accepted，否则会作为等待你接受／拒绝的建议发布——该标志是自主模式实现自主运行的关键。
resolve_comment	id · note	编辑完成后将评论标记为已处理，并用一行文字说明所做的更改。评论会在工作区中变成绿色，供你检查。
reply_to_comment	id · text · role?（author | reviewer | defender）	添加串接回复，让双方可以直接针对评论解决分歧，而不是在聊天中讨论。
show_diff	checkpoint?	将并排差异渲染成图片，并直接显示在对话中。默认显示当前尚未提交的更改；传入检查点 sha 可查看已保存的版本。
list_checkpoints	limit?（默认 10，最多 50）	按时间倒序列出最近的检查点及其 sha——用它找出一个传给 show_diff。

主要工作流是基于这些工具构建的，并不属于这些工具。 /magic-latex、 /ai-review、/address-comments 和 ⚡ /ultra-agents 是 Claude Code 插件命令，用于编排上述工具——/ultra-agents 会串联审阅 → 自动接受 → 修复，并根据你允许的轮数重复执行；这也是 add_comment 带有 accepted 标志的原因。它们不属于 MCP 接口，因此其他 MCP 客户端只能看到这七个工具。请参阅插件部分 和 docs/AGENT-LOOP.md。

在终端中查看

以下是实际运行时针对示例论文捕获的真实工具输出，未经修改，并非模拟内容。浏览器工作区（上方截图）实时呈现同一状态时，你在 Claude Code 中看到的就是这些内容。

你输入：

/magic-latex

Claude 调用 render_preview 并回复：

✓ Compiled main.tex with xelatex in 1900ms — 2 files. Workspace (live preview,
source editor, history, PDF comments — auto-reloads on edits):
http://127.0.0.1:52042/app

你（或审阅技能）留下评论，然后询问有哪些内容已准备好处理。Claude 调用 check_comments：

1 accepted comment — edit each at its source location per the instruction, then
call resolve_comment with its id and a one-line note:

[id: 2fce9e3c8b5f] p.1 — "Sorting widgets efficiently is a long-standing problem"
  ↳ source: main.tex:15
  → Tighten this opening sentence.

(1 reviewer suggestion still awaits the human's accept in the workspace — not
actionable yet.)

Claude 进行编辑并调用 resolve_comment：

✓ Resolved comment 2fce9e3c8b5f ("Sorting widgets efficiently is a long-standing
problem…") — the card now shows: Rewrote the opening sentence.

再次询问后，已接受队列为空——只剩下尚未接受的建议，等待你处理：

No accepted comments. (2 already resolved.)

(1 reviewer suggestion still awaits the human's accept in the workspace — not
actionable yet.)

工作原理

Claude edits .tex ─┐
 file watcher ─────┼─▶ compile coordinator ─▶ headless Chromium ─▶ WASM TeX ─▶ PDF
 render_preview ───┘         (serialized)         (engine host)                │
                                                                               ▼
                     your workspace (/app)  ◀── WebSocket "reload" ◀── local HTTP server
                     Source · PDF · History · Comments        (serves /app + /latest.pdf)

WASM 引擎需要 DOM/Worker 全局对象，因此服务端会托管一个隐藏的无头 Chromium 作为编译工作进程；你打开的工作区则是一个轻量级 React + pdf.js 应用，不包含 WASM。请参阅 docs/ARCHITECTURE.md。

flowchart LR
  H["👤 You<br/>Source · PDF · History · Comments"]
  A["🤖 Claude Code<br/>+ review / author agents"]

  H <-->|"select text →<br/>anchor comment"| SRV["Preview server<br/>HTTP + WebSocket · serves /app"]
  A -->|"7 MCP tools"| MCP["MCP server<br/>render_preview · show_diff · list_checkpoints<br/>check / resolve / add / reply_comment"]

  SRV --> CO["Compile coordinator<br/>(serialized)"]
  MCP --> CO
  A -. edits source .-> FILES[("Paper files · git repo")]
  FILES --> WATCH["File watcher"] --> CO
  CO --> ENG["WASM busytex<br/>(headless Chromium)"] --> PDF["/latest.pdf"]
  PDF -. live reload .-> H
  CO --> CK["git checkpoints<br/>(hidden ref) → History"]

  SRV <--> CJSON[(".latex-preview/<br/>comments.json")]
  MCP <--> CJSON
  CJSON -->|"check_comments<br/>(your accepted asks)"| A

两种入口——你在工作区中使用的入口，以及 Agent 通过 7 个 MCP 工具使用的入口——都连接到同一个协调器、评论存储和 git 历史记录。你操作的是渲染后的文档（锚定评论）；Claude 操作的是源文件（通过 check_comments 读取你的评论、进行编辑、调用 resolve_comment）。这个共享基础让评论循环、审阅工作流和可追溯历史成为可能。

要求

• Node 20.19+（这是 chokidar 和 playwright 实际要求的最低版本；服务端会在启动时检查并提示）
• Playwright 的 Chromium（自动安装；约 150–300 MB），或者设置为复用已安装的 Chrome。
• 首次下载 WASM TeX Live 资源需要约 650 MB 磁盘空间，所有资源都会在首次运行时下载，分为三个软件包组（basic 87 MB、recommended 190 MB、extra 324 MB，另加 31 MB 引擎）。普通论文只会加载 basic 组；较大的两个组会留在磁盘上，直到有内容需要它们。资源按用户缓存，而不是按安装缓存，因此升级 MagicTeX 时无需重新下载。使用 MAGICTEX_ASSETS_DIR 覆盖存储位置。
• 本地 TeX 安装不是必需的。 详情请参阅下文，了解何时需要安装。

我需要本地 TeX 发行版吗？

不需要——捆绑的 WASM 引擎无需安装任何内容即可编译，这正是它的设计目的。不过，它只包含 TeX Live 的一个子集，因此有些内容不在其中：svg、大多数会议论文模板类，以及各种不太常见的软件包。缺少某项内容时，系统会告知你，而不会悄悄生成错误的 PDF。

如果你希望输出与 Overleaf 完全一致，请安装一个发行版。MagicTeX 会自动检测，无需配置：

macOS	MacTeX
Linux	通过软件包管理器安装 texlive-full
Windows	TeX Live，或 MiKTeX 加上 Strawberry Perl

MagicTeX 会在 PATH 中查找 latexmk，但它并非可以单独安装的程序——它是上述发行版中附带的驱动脚本。请使用 latexmk -version 检查，而不是使用 which latexmk：latexmk 是 Perl 脚本，而 MiKTeX 会将 latexmk.exe 放入你的 PATH，却不附带运行它所需的 Perl，因此虽然能找到文件，仍无法执行。在 macOS 上，你可能需要先运行 eval "$(/usr/libexec/path_helper)"，或重新打开终端。

每次编译都会告知你使用的是哪种引擎——xelatex · system 或 xelatex · wasm。

开发

npm install
npm run typecheck    # tsc for the server and the UI
npm run build:ui     # build the React workspace to ui/dist
npm test             # the unit suite — engine-free, no browser, seconds
npm start            # run the server on stdio (for a manual MCP client)

有意分为两个层级。npm test 会测试评论存储、锚点匹配、行列几何、历史记录仓库、资源路径、编译日志分类、预览服务关闭，以及 MCP 工作流端到端测试——全程无需浏览器或 TeX 引擎，因此速度快且结果确定。每次推送和拉取请求时，CI（.github/workflows/ci.yml）都会在 Node 20 和 22 上运行类型检查、UI 构建和这套测试。

单元测试从结构上无法覆盖的内容——多个缩放级别下的高亮几何、编译失败实际会向读者传达什么，以及关闭时是否会关闭服务并警告已打开的窗口——则由 scripts/smoke-*.mjs 覆盖，并在 .github/workflows/smoke-macos.yml 中通过真实浏览器和真实编译运行。每项测试的存在，都是因为曾有问题随一个全绿的单元测试套件一起发布。请保持两套测试都通过，并随改动补充覆盖。

文档

• 用户指南 — 日常使用、评论循环、Visual 模式、文件树、将论文导入 Overleaf、软件包覆盖范围。
• Agent 循环 — 以评论作为触发条件、使用 /loop 无人值守运行、审阅者 → 守门人 → 解决者工作流，以及 ⚡ /ultra-agents。
• 路线图 — 已实现的并发 Agent 功能，以及真正的并行多 Agent 编辑还需要什么。
• 架构 — 为什么使用无头浏览器、每个模块的作用、编译流程。

以上四份文档都已翻译成与本 README 相同的 8 种语言——每个页面顶部都有自己的语言切换器。

路线图

多个 Claude Code 会话现在已经可以同时处理同一个项目，而不会破坏评论或检查点历史（参见 docs/ROADMAP.md）——真正的并行多 Agent 编辑（审阅者／作者／辩护者各自在自己的 git 分支上工作，再合并到一起）是下一个里程碑。

赞助本项目

MagicTeX 免费且开源（AGPL-3.0）。如果它为你的论文节省了时间，请考虑**赞助本项目**——这有助于持续开发。也欢迎在仓库点亮 ⭐。

致谢

MagicTeX 由 Zoe Lin 编写并维护，使用 Claude Code 构建。

感谢 David Turnbull 告诉我 Knuth 宁愿花十年打造自己的排版系统，也不愿接受自己书籍的呈现效果——这个项目始终在与这个故事争辩。还要感谢 texlyre-busytex 的维护者；没有他们的 WASM TeX Live，这一切根本无法在本地运行。

许可证

AGPL-3.0-or-later — 与本项目所基于的 texlyre-busytex 引擎一致。参见 THIRD_PARTY_NOTICES.md。