Skip to content

Home

Jump to bottom
zhangxh edited this page Aug 17, 2026 · 5 revisions

TeXLeaf Wiki

TeXLeaf 是面向 VS Code 桌面版的 LaTeX 写作扩展，把四个彼此配合、又可以分别关闭的功能集中到一个插件中：

  1. 片段：212 条可编辑 Snippet、四个整篇 TeX 模板、数学输入辅助和结构化管理器；
  2. AI 写作：默认关闭、由用户自己的 DeepSeek Chat Completions 或 OpenAI Responses API 驱动的正文检查、改写与行内补全；
  3. 文献：项目 bibliography 与 Zotero/Better BibTeX 联动的 VS Code 原生引用补全；
  4. 预览：离线 MathJax 4 SVG 活动公式预览。

本 Wiki 对应 TeXLeaf 1.0.0。扩展支持 Windows、macOS 和 Linux 上的 VS Code 1.98+。AI 写作需要用户自行提供所选服务商的 API Key；默认 Provider 是 DeepSeek，默认请求 https://api.deepseek.com/chat/completions，也可配置兼容 Chat Completions + JSON Output 的 Base URL。OpenAI Provider 默认使用 gpt-5.6-luna 和 https://api.openai.com/v1/responses，也可配置兼容 Responses + Structured Outputs 的 Base URL。Math Preview 的产品方向受到 Ultra Math Preview 与 hscopes-booster 启发，TeXLeaf 当前把活动公式渲染资源随 VSIX 一起提供；扩展不接管 LaTeX 编译流程。完整来源和联合开发说明见 致谢与联合开发。

安装

  1. 优先打开 Visual Studio Marketplace 安装 zhangxh-math.texleaf。
  2. 也可以从项目的 GitHub Releases 下载对应版本的 VSIX。
  3. 使用 VSIX 时，在 VS Code 运行 Extensions: Install from VSIX...，选择下载的文件并按提示重新加载窗口。

源码仓库只保存源码、测试、模板、文档和许可证。*.vsix、构建目录和其他二进制产物不会提交到源码分支；经过验证的 VSIX 只作为 GitHub Release 资产发布。详见 开发与发布。

从旧 local-lab.texleaf 升级时，不要直接卸载旧版：先保存修改和备份自定义模板，安装新版后禁用旧版并 Reload Window，让 zhangxh-math.texleaf 检查并迁移同一 Profile 的有效全局 Snippet；确认数据无误后再卸载旧版。完整步骤与模板/Settings Sync 边界见 片段与模板。

三分钟上手

片段

先把一个新文件保存为 .tex，然后尝试：

输入 结果
lm 自动展开为 \(...\)
dm 自动展开为缩进正确的 \[...\]
\thm 自动创建 theorem 环境
\dfn 自动创建 definition 环境
;a（数学区域） \alpha
//（数学区域） 带 tabstop 的 \frac{...}{...}
article-cn（空白 .tex） 中文 article 模板
article-en（空白 .tex） 英文 article 模板

按 Ctrl+Shift+P / Cmd+Shift+P 运行 TeXLeaf: 管理 Snippet 与模板，可以搜索、添加、复制、修改、删除和批量替换 Snippet 或模板。完整说明见 片段与模板；自定义规则语法见 Snippet 格式。

0.8.10 起，原生 Suggest 只显示与光标前输入具有非空 trigger 前缀匹配的 TeXLeaf 片段；继续输入后已经不再匹配的条目会被移除。要不依赖当前输入浏览当前上下文可直接插入的普通片段，请按 Ctrl+Alt+L（macOS 为 Cmd+Alt+L）。默认开启 Tabout 时，Suggest 已打开且当前位置确实有可越过的右括号、\rangle 或数学结束分隔符，Tab 才会优先跳出；没有真实 Tabout 目标时仍接受 VS Code 当前选中的补全。数学区域的活动 Snippet Session 若仍有下一 tabstop，会先关闭 Suggest、再前往该占位符；Suggest/Tabout 路径不会抢占精确 TeXLeaf trigger、Inline Suggest 或 Rename 输入框。Matrix/Align 在 1.0.0 中改为局部 Tabout 优先、没有目标才插列。

0.8.11 修复了无显式 tabstop 的普通片段在自动放大括号后的光标位置：例如 (sum) 展开成 \left(\sum|\right)，可以在右定界符内继续输入；输入 +、上下标等内容、使当前位置没有精确手动片段 trigger 后，按一次 Tab 可跳出。刚停在 \sum 后直接按 Tab 时，既有 sum-limits 手动片段仍优先展开；原本带 tabstop 的片段仍按自身顺序导航。

1.0.0 的 TeXLeaf 候选筛选保留当前全部适用片段中的全局最长非零前缀组，并额外保留所有已完整输入的 literal trigger，避免 regex shadow 或重复 ID 使完整字面量候选消失。只有 runtime 唯一选中的 exact literal 获得 Keyword 类型、preselect 与 exact sort 优先级；其他完整 literal 仍按普通 Snippet 候选排序。输入 ss 时保留匹配两个字符的 SS2、SSE、SSP、SSS，不会混入只匹配末尾单个 s 的 sum、sim、sub、sup；第三方 Provider 的候选仍由 VS Code 合并，TeXLeaf 不能删除。

1.0.0 还把 align / matrix 的括号推断和 Tabout 限制在当前数学列表：自动放大不会跨未转义的 &、\\、\cr、\crcr 或 \tabularnewline 配对括号；当前单元格确有右侧闭合符时，Tab 先跳出，只有没有局部目标时才插入下一列的 &。因此在 \frac{1}{n^{2}|} 中第一次 Tab 越过分母右花括号，下一次没有局部闭合符时才插列；Tabout 不会跳到下一单元格或下一行。

1.0.0 只考虑一次旧 article factory trigger 迁移：当前仍为 tmpa-cn / tmpa-en 时分别尝试改为 article-cn / article-en，当前已经是其他值时不改。迁移 marker 会先写入；目标冲突、前缀冲突或提交失败时保留旧值并写入 Output → TeXLeaf，以后不重试，用户日后主动改回旧 trigger 也不会再次迁移。Beamer 默认 trigger 仍为 beamer-cn / beamer-en。

AI 写作

AI 写作安装后默认关闭，不会自动发送论文。首次使用时：

  1. 在受信任工作区打开一个已有文件名和路径的本地/Remote .tex；
  2. 在 Settings 选择 DeepSeek 或 OpenAI，并确认该 Provider 的模型和 Base URL；
  3. 运行 TeXLeaf: 切换 AI 写作助手；
  4. 核对提示中的实际正文接收目标、隐私与独立计费说明；
  5. 确认后，在密码输入框中设置当前服务商/当前 Base URL 专用的 API Key；
  6. 在普通正文中运行 TeXLeaf: AI 检查当前段落或选区。

建议通过编辑器装饰线、TeXLeaf 专用 Hover、灯泡 Quick Fix 和活动栏“AI 写作问题”列表显示；0.8.9 的 Hover 还可以直接点击“应用这条建议”，该白名单内部命令仍会在后端重新核对文档版本、问题身份、范围、exact original 与 editable prose。AI 问题不发布为原生 Diagnostic，也不会重复进入 Problems。TeXLeaf 还支持整篇分段检查、纯正文改写和可单独关闭的行内补全。注释、citation、label、URL、代码环境和未知 TeX 结构会先在本地按 fail-closed 原则等长遮罩；公式改用不可编辑的等长语义占位符，公式内容不会发送，模型却能知道此处有 inline/display formula，从而保持语法上下文。TeXLeaf 0.8.9 能安全处理模型按 UTF-16、Unicode code point、UTF-8 byte 或 CRLF 换行计数返回的常见 offset 差异，但只接受 original 的无歧义逐字映射；用户的语言设置会先映射为 auto / English / Chinese 短标签，避免在本地误触发 language-too-long；message/explanation 仍要求简体中文，replacement 保持正文原语言。完整的发送范围、SecretStorage、费用与安全边界见 AI 写作助手。

“AI 写作问题”列表按行号展示类别、真实严重性、原文 → 替换 与解释，支持单条应用/忽略，以及确认后重新校验的“应用全部”。点击条目会滚动到问题范围，并给对应正文叠加主题自适应背景与轮廓；其他问题仍保留下划线。该高亮不移动主光标、不触发诊断音效，会沿稳定 issue lineage 跟随无关前文编辑，并在应用、忽略、清除、失效或关闭 AI 后自动移除。单条或批量应用成功后，对应问题会立即从装饰线、Hover、树和持久缓存中消费；在问题右端点追加词尾也会使旧词形建议失效。安全平移的未受影响问题会保留稳定 lineage ID，因此刷新前已经显示的树节点或 Quick Fix 仍可在当前正文上重新验证并应用；真正失效的旧节点只刷新列表并显示短状态栏提示，不再弹出“文档已变化”或播放音效。“应用全部”确认后会按稳定 ID 重新解析当前安全问题，等价 state 对象刷新不会误终止；正文版本已变、任一捕获问题已移除/失效/无法唯一解析，或者范围、原文或重叠校验失败时仍整批拒绝。确认后才出现、未被确认的其他建议不属于这一批。当前正文若已由候选的 original 范围加紧邻上下文组成完整 replacement，该截短候选会在线上校验和缓存恢复时被拒绝。自动检查把旧句与新句并集作为 provider 上下文，但只让实际编辑及累计 pending 的精确范围失效：同一句中不相交的问题在 exact original、strict UTF-16 remap 与 editable prose 都成立时继续保留；自动回应也只替换命中局部范围或与新问题相交的旧项。句号/空行 split/merge、多处编辑、零宽边界和中文无空格分句都纳入该模型。每句成功立即合并，后续 API 失败不回滚前句；剩余 pending 句子会明确显示。每批最多 8 句，每版本最多自动请求 64 个不同句子，手动整篇每次最多 32 个正文段。保存等空 change 不清结果。TeXLeaf 不播放音频；装饰线与专用 Hover 不产生原生 Diagnostic 的重复 Hover 或 Error/Warning accessibility signal，树仍显示真实严重性。Windows 微软拼音中文模式会优先占用 Ctrl+. 切换中英文标点；可按 Shift 切到英文输入模式再使用该键，或通过 F1 / Command Palette、右键、灯泡及 Hover 链接应用建议。TeXLeaf 没有新增专用快捷键。经过校验的问题会在本机 globalStorage 跨重启恢复，但不写工作区、不 Sync、不保存论文全文；只有完整源码长度与 SHA-256 和快照完全一致时才按原 offset 恢复，外部改动、旧截短记录或缓存不匹配会安全丢弃并要求重检。网络延迟、限额与费用决定它是近实时，而不是每键联网的本地即时检查；总开关仍默认关闭。

文献

  1. 在工作区中准备 reference.bib，或保留默认设置让 TeXLeaf 在首次导入时创建它。
  2. 启动 Zotero 桌面端；推荐安装与当前 Zotero 版本兼容的 Better BibTeX。
  3. 在 Zotero 设置中允许本机其他应用通信。
  4. 在已保存的 .tex 文件中输入 \cite{}，把光标放在大括号内。

TeXLeaf 的原生 Suggest 条目左侧只显示标题和来源；选中后右侧按字段显示标题、作者、期刊/出版物、年份、Citation key、来源和收录/导入状态，不再在顶部重复一行“作者 · 期刊 · 年份”。搜索字段严格是 citation key、标题、作者、年份、DOI 和 ISBN；不搜索期刊/出版物、摘要、标签或笔记，也不做拼写纠错。多词查询规范化、去重后按 AND 组合，可以跨字段命中。结果依次偏好精确原始 key、紧凑 key/前缀、精确 DOI/ISBN、全词/词首和普通子串；相关度相同时才偏好 bibliography 来源。TeXLeaf 先对 bibliography 与 Zotero 全库快照做本地匹配和排序，再把最多 100 条交给 Suggest；继续输入会重算全库，因此先前未进入前 100 条的文献仍可出现。每键过滤不请求 Zotero。同一个 \cite{...} 内可用逗号连续添加多篇文献。

连接、去重、BibTeX/BibLaTeX 和远程环境边界见 文献与 Zotero。

预览

把光标移入 $...$、\(...\)、\[...\]、$$...$$ 或常见数学环境。默认 cursor 模式会显示当前公式的圆角、不透明 SVG 预览：

  • 行内公式随光标所在行移动，默认的 autoBelow 优先位于下方；
  • 行间公式与 opening delimiter 对齐；
  • 深浅主题使用不同的高对比公式色和光标色；
  • 渲染在扩展自带的后台 Worker 中离线完成。

cursor / both 在连续输入时保留 last-known-good 预览，并用单一稳定 decoration 原位换帧；临时渲染失败有 750 ms 宽限，Hover SVG 按需写盘，因此 cursor 卡片不会再每键消失。离开公式、禁用、Dismiss 或停在无效状态超过宽限仍会清理。原生 hover 在输入时仍可能由 VS Code 自行关闭。

1.0.0 提供对称命名的 placement=autoBelow（自动、优先下方，默认）和 placement=autoAbove（自动、优先上方）。两种自动模式都会在首选侧空间不足时尝试另一侧，上下都不足时都强制使用上方并共用超高公式的末尾保留策略。需要固定方向时可显式选择 above 或 below。旧值 auto 仍按 autoBelow 运行，但不再显示在设置选项中。

TeXLeaf 专注于 VS Code 源码编辑器中的活动公式轻量预览，不提供整篇所见即所得替换或内置 PDF 面板。原因和定位边界见 Math Preview。

设置入口

在 VS Code Settings 中搜索：

@ext:zhangxh-math.texleaf

用户可见设置严格分为四组：

  • TeXLeaf · 片段
  • TeXLeaf · 文献
  • TeXLeaf · AI 写作
  • TeXLeaf · 预览

全部 52 个设置、默认值、命令和快捷键见 配置参考。

支持范围与重要边界

  • 编辑功能只在已保存的 .tex 或 .bib 文件中运行；Untitled、.md 和其他后缀不会因为 language ID 看起来像 LaTeX 就自动展开。
  • AI 写作更严格：只在受信任窗口中已有文件名和路径的本地 file: 或 Remote vscode-remote: .tex 正文运行；.bib 不会发送。请求使用当前编辑器内存内容，因此可能包含尚未写入磁盘的编辑。功能默认关闭，全部 14 个普通设置只能位于用户/Profile application 层并可随 Settings Sync 同步；工作区不能开启、重定向或换模型，SecretStorage Key 与 consent 不同步。
  • TeXLeaf AI 提供 Grammarly 风格工作流，但不是 Grammarly 的功能等价实现；模型建议需要作者复核。DeepSeek、OpenAI API 和自定义 Chat Completions/Responses 服务各自独立计费，ChatGPT Plus/Pro/Codex 订阅不等于 OpenAI API 额度。
  • DeepSeek 自定义 Base URL 只支持 {Base URL}/chat/completions 与 JSON Output；OpenAI 自定义 Base URL 只支持 {Base URL}/responses 与 Structured Outputs。远程地址必须使用 HTTPS，只有 loopback 可用 HTTP，请求不会跟随重定向或跨协议回退。每个规范化 URL 使用独立 Key/consent；默认 DeepSeek 官方 URL 继续兼容旧 v1 记录，自定义 URL 绝不复用。TeXLeaf 对 OpenAI 发送 store:false，但第三方是否存储或训练仍由其政策决定。
  • Zotero 请求固定连接 127.0.0.1，不会连接任意远程主机，也不会访问 Zotero 云端账户。
  • 未信任工作区不会访问 Zotero 端口、创建 bibliography 或加载项目附加 Snippet 文件。
  • VS Code 会合并所有 Completion Provider。TeXLeaf 能控制自己的候选，但不能删除 LaTeX Workshop 等第三方扩展提供的 citation 候选；详见 文献与 Zotero。
  • Math Preview 是不改变文档内容的 decoration 浮层，不能给正文真正预留空间；autoBelow / autoAbove 只能依据公式边界和可见行选择方向，超宽公式或紧邻正文仍可能造成裁切或遮挡。
  • Settings Sync 由用户自行开启；它同步有效的 Profile 内部库，不等同于实时协作编辑，也不会自动在另一台机器安装手工分发的 VSIX。

文档导航

如需报告问题，请先阅读 故障排查，并附上 VS Code/TeXLeaf/Zotero/Better BibTeX 版本、操作系统、复现步骤，以及 Output → TeXLeaf 中与问题相关但已去除隐私的日志。

TeXLeaf 1.0.0

开始

片段

AI 写作

文献

预览

贡献与发布

Clone this wiki locally