LaTeX 写作与编译¶

LaTeX 编辑使用 CodeMirror；正式编译走本机 latexmk，PDF 使用已有 EmbedPDF 查看器；实时预览走独立 LuaLaTeX/rtex 会话。后端见 ../backend/latex.md。写作项目位于文件树的「写作」目录，源码、PDF 与论文库共用工作区；多个项目各自编译。见 writing.md。

界面与编译¶

当前文件属于 LaTeX 项目时，左栏显示整篇论文的结构。写作项目内的目录及文件统一进入项目编辑面板，文件内容和编译预览组成同一个面板，编译工具位于预览顶部，不与笔记标签混排；选中编译产物 PDF 恢复项目源码与预览，其他项目内素材 PDF 在左侧查看，项目外 PDF 保持普通阅读视图。编译、实时预览、引擎选择与诊断沿用写作工具栏。

普通编译保留当前文件与活动编辑 pane，只刷新已打开的 PDF，不自动打开或激活 PDF；“查看 PDF”负责打开/切换预览。文件树与 LaTeX 侧栏的编译、强制重建、清理后重建遵循同一规则。文件树的编译图标保持透明背景，按下时不触发整行的按下底色，保留选中状态和键盘焦点提示。编译使用 latexmk 的增量判断；强制重建无视增量缓存；清理后重建先清除中间产物、保留 PDF。
手动保存先保存所有挂载的文本编辑器，再编译项目主文件；后台自动编译可按项目选择手动、保存后或依赖变化时触发。
编译期间保留上一份成功 PDF，可以继续阅读；只有没有旧产物时才显示加载占位。成功后替换所有同路径 PDF 分屏的字节，恢复页码、阅读点和缩放；失败时保留旧 PDF。
问题保持编辑页面底部原有计数与悬停列表，也可用键盘聚焦打开。只显示 ChkTeX 原始规则结果，浮层保留消息中的规则编号，不另起一行重复显示来源，单击定位；文字可拖选并使用系统复制，拖选结束不会跳转。每条末尾平时显示行列，悬停或键盘聚焦时在原位换为紧凑复制图标（触屏常显），复制当前问题的文件、行列、严重度和原始规则消息；不提供复制全部。不启用语言包诊断或自写项目诊断。编译失败不进这份列表，由任务面板和下方「日志」入口呈现。
实时预览状态：入口名称始终为“实时预览”；开启时整行淡色高亮、文字右上方紧跟常亮绿点；背景复用主题 CSS 变量 --primary 并降低不透明度，绿点保持统一的绿色状态色。关闭时恢复普通背景并隐藏绿点（保留占位）。点击整行切换，键盘与读屏通过 toggle button 的 aria-pressed 获取状态，不另加开关或引擎后缀。
编译按钮空闲时显示「编译」。编译中保持主色，主按钮只留一个居中的转圈、不显示文字，按钮宽度沿用空闲时占位所以下拉控件不会抖动，左右两半一起处于忙碌态，不再一半变灰、一半可点；菜单里不能再次编译，停止编译仍可用。结束、失败或取消后立即恢复，成功只短暂显示「编译成功」。没有引擎时按钮变灰且不转圈，和编译中区分开。
日志从写作 PDF 顶栏的叹号进入问题卡片，再点击卡片底部的「编译日志」打开完整列表；左侧列出问题，右侧显示原始构建输出（writing-problems.tsx）。叹号平时为黄色，有编译错误时变红；编译失败而日志里解析不出错误行时，卡片补一条错误，内容取构建返回的诊断。显示该主文件的项目编辑面板处于焦点时，编译失败只把叹号标红，不弹 toast；没有这样的面板时仍弹 toast（showTexProblemsView）。日志对话框与任务面板支持停止编译。

编辑器不会为每次自动构建弹成功 toast；操作失败通过 notifyError 提示，编译失败的例外见上面的「日志」。LaTeX 侧栏没有第二份问题计数或问题列表。

项目设置与配方¶

主文件自动识别支持 % !TEX root、自身 document 标记、反向 include 图和 subfiles 的父文件。项目设置可显式选择主文件，或让某个 subfile 独立编译；选择随本机工作区保留。

引擎按根文件 % !TEX program / % !TEX TS-program → 项目里记住的选择 → 模板要求的引擎（会议模板为 pdfLaTeX，babelfont 为 LuaLaTeX）→ XeLaTeX / 已安装引擎的顺序选择。实时预览固定使用 LuaLaTeX，切换预览不会改正式编译引擎。

项目设置支持输出目录、中间产物目录、输出文件名、编译后跟随源码光标，以及多个命名构建配方。配方列表使用 JSON 编辑，侧栏选择当前配方并记忆；默认项仍使用项目引擎驱动 latexmk。

[
  {
    "name": "LuaLaTeX + latexmk",
    "tools": [
      {
        "command": "latexmk",
        "args": ["-lualatex", "-synctex=1", "-file-line-error", "-recorder", "-interaction=nonstopmode", "-outdir=%OUTDIR%", "%DOC%"]
      }
    ]
  }
]

工具可设置独立 cwd 和 env，支持 %DOC%、%DOCFILE%、%DIR%、%OUTDIR%、%AUXDIR%、%JOBNAME%。占位符含义与执行约束见后端文档。项目设置是本机偏好；已有 .latexmkrc 继续由 latexmk 按自身规则读取。

自动编译与导航¶

自动编译按主文件合并请求，1 秒防抖；编译中继续编辑只留下尾随请求。显式重建不会被自动请求降级。依赖来自项目扫描与所选产物目录的 .fls，同时保留 .bib；编译中间产物不会反过来触发构建循环。切换 Vault 清除待触发的旧项目请求。

编辑器里按 Mod-Alt-j（项目 PDF 也可用边缘的定位按钮）将源码光标定位到 PDF；PDF 中修饰键点击跳回源码，包含章节文件。定位处理缩放、旋转页、分屏和异步加载；编译后跟随只作用于新产物版本，关闭时不会抢走阅读位置。自定义输出 PDF 的 texRoot 随工作区布局持久化。

写作辅助¶

\cite{} 搜索整项目 bibliography，按 key、标题和作者过滤；同时识别 .tex 中 thebibliography 的 \bibitem，用于补全、预览与定义跳转。
\ref{} 等引用搜索所有章节的标签；F12 或修饰键点击打开定义。\href 的 URL 与 \hyperref 的显示文字不会被当成 label。
悬停公式、标签引用和文献引用显示预览；公式使用 KaTeX，完整排版以编译 PDF 为准。
大纲按章节层级列出整篇论文的结构，跨文件合并成同一棵树，不显示源文件行；标签、图、表挂在其所在章节下，点击任意一行定位源码。切换文件时保留上一份完整结构，新文件索引就绪前不收缩。
工具栏的论文库引用入口可以搜索当前 Vault 论文，写入项目 bibliography 并插入 citation key；按 DOI / arXiv / 标题去重，处理 key 冲突。已声明但不存在的 .bib 会按声明创建；没有声明时添加必要的 bibliography 接入代码。
保存成功或外部 .tex / .bib 变化会刷新项目索引与大纲；格式化入口已按产品决定移除。

代码入口与验证¶

lib/tex/config.ts 保存项目偏好；build-queue.ts / auto-build.ts 负责调度；build-state.ts 汇总构建输出；project-index.ts 提供补全、引用跳转与大纲共享的项目索引；synctex.ts 负责源码与 PDF 导航。写作里编译和日志在 PDF 顶栏，引擎和项目设置在应用设置的「写作」，结构在 writing-outline.tsx，引用在 tex-citation-picker.tsx。

lib/workspace/tex-outline-bridge.ts 只发布大纲快照；大纲点击通过 lib/tex/editor-navigation.ts 的 navigateTexSource 定位源码。

pnpm exec vitest run test/tex-*.test.ts test/pdf-reload-position.test.ts
pnpm typecheck

当前以本机桌面项目为范围。TeX 宏展开生成的动态路径与完整包语义仍以实际编译结果为准；实时预览的字体、分页和全文搜索限制见 ../backend/rtex.md。