Configuration

配置参考

在 VS Code Settings 中搜索：

@ext:zhangxh-math.texleaf

TeXLeaf 1.0.0 的 52 个用户可见设置分为四组：

1. TeXLeaf · 片段：22 项；
2. TeXLeaf · 文献：9 项；
3. TeXLeaf · AI 写作：14 项；
4. TeXLeaf · 预览：7 项。

没有单独“高级”组；高级匹配参数归入“片段”。片段、文献和预览设置的 scope 是 resource，可以在用户、工作区、工作区文件夹或语言级范围覆盖；全部 14 个 AI 写作设置的 scope 是 application，只能在用户或当前 Profile 层配置，并可随普通 VS Code Settings Sync 同步。工作区、工作区文件夹和 .vscode/settings.json 不能开启 AI、重定向目标、切换 Provider/模型，或修改防抖与发送长度等费用相关参数。数组和对象较适合在 settings.json 中编辑。

TeXLeaf · 片段

设置	默认值	作用
texleaf.enabled	true	TeXLeaf 总开关
texleaf.autoSnippets	true	自动展开带 A 选项的 Snippet 和整篇模板
texleaf.manualTrigger	"tab"	非自动规则确认键：tab 或 space
texleaf.autoFraction	true	数学区域输入 / 后把左侧局部表达式转换为分式
texleaf.autoFractionCommand	"\\frac"	自动分数使用的命令，如 \frac、\dfrac、\tfrac
texleaf.autoEnlargeBrackets	true	高结构插入后辅助把包围括号改为 \left/\right
texleaf.visualSnippets	true	启用选择区包裹规则
texleaf.matrixShortcuts	true	matrix/align 的 Tab/Enter/Shift+Enter 和安全 left/right 跨行 Enter
texleaf.tabout	true	Tab 跳过 tabstop、闭括号或数学定界符
texleaf.skipPairedClosingCharacters	true	已有 )、]、} 前输入同字符时只越过
texleaf.autoDeleteMathDelimiters	true	空数学定界符内 Backspace 删除整对
texleaf.colorizeBrackets	true	数学区域按嵌套深度着色括号
texleaf.highlightActiveBracketPair	true	高亮光标附近或包围光标的括号对
texleaf.enableCompletions	true	把全部适用片段中匹配长度最长、且长度非零的 trigger 组提供给原生 Suggest，并额外保留所有已完整输入的 literal trigger；只有 runtime 唯一选中的 exact literal 获得 Keyword/preselect/exact sort 优先级；用 Ctrl+Alt+L 浏览当前上下文可直接插入的普通片段
texleaf.languageIds	['latex','tex','bibtex']	允许的 language ID；仍只作用于已保存 .tex/.bib
texleaf.snippetFiles	[]	显式项目附加 JSON/JSONC 相对路径
texleaf.excludedEnvironments	['verbatim','lstlisting','minted']	禁止自动片段和自动分数的环境
texleaf.matrixEnvironments	matrix/align 默认列表	启用矩阵快捷键的环境名
texleaf.autoFractionBreakingCharacters	"+-=,;:&"	自动分数向左扫描的停止字符
texleaf.autoEnlargeTriggers	['\\frac','\\sum','\\prod','\\int','\\lim']	触发括号放大的命令
texleaf.maxRegexScanLength	512	正则规则向光标前扫描长度，范围 64–8192
texleaf.wordDelimiters	"., +-\\n\\t:;!?\\/{}[]()=~$"	w 选项认可的词边界；\n/\t 会解码

texleaf.autoEnlargeBrackets 开启时，如果一个无显式 tabstop 的普通片段使整个括号范围改写为 \left...\right，0.8.11 会把光标恢复到生成的 \right 前。例如 (sum) 得到 \left(\sum|\right)；继续输入 +、上下标等内容，使当前位置没有精确手动片段 trigger 后，按一次 Tab 执行 Tabout。刚停在 \sum 后直接按 Tab 时，既有 sum-limits 手动片段优先展开；已经声明 tabstop 的片段不添加合成占位符，仍使用原顺序。

1.0.0 起，自动放大与 Tabout 都尊重 TeX 对齐边界：未转义的 &、\\、\cr、\crcr、\tabularnewline 会分隔单元格或行；注释中的同形文本和转义的 \& 不算边界。自动放大不会跨边界生成 \left...\right，Tabout 也不会到下一单元格/下一行找闭合符。普通源码换行本身不结束 TeX 行；同一 cell 的合法跨物理换行 pair 仍会放大，并保留原换行与缩进。Matrix/Align 中的 Tab 顺序是：精确片段或活动 snippet tabstop、当前单元格内的真实 Tabout、最后才是插入 &。

matrixEnvironments 的完整默认值：

[
  "matrix", "pmatrix", "bmatrix", "Bmatrix",
  "vmatrix", "Vmatrix", "array", "cases",
  "align", "align*", "aligned"
]

片段管理、默认规则和模板见 片段与模板；数据语法见 Snippet 格式。

TeXLeaf · 文献

设置	默认值 / 范围	作用
texleaf.zoteroCitations	true	文献/Zotero 总开关；未信任工作区强制停用
texleaf.bibliographyFile	"reference.bib"	工作区内相对 .bib 路径
texleaf.bibliographyFormat	"bibtex"	新导入条目格式：bibtex 或 biblatex
texleaf.autoShowCitationPicker	true	进入 citation 参数时自动触发原生 Suggest
texleaf.citationCommands	见下方	可触发补全的命令；星号变体自动兼容
texleaf.zoteroLibrary	"My Library"	library 名称或内部数字 ID
texleaf.zoteroPort	23119，1–65535	Zotero/BBT 端口；主机固定 127.0.0.1；Juris-M 常见 24119
texleaf.zoteroRequestTimeoutMs	10000，500–60000	本机请求超时，毫秒
texleaf.zoteroCacheSeconds	30，0–3600	文献列表内存缓存时间；0 表示每次过期刷新

默认 citation commands：

[
  "cite", "citep", "citet", "Cite", "Citet",
  "autocite", "parencite", "textcite", "footcite", "supercite"
]

命令名可以带或不带开头反斜杠，必须是安全的 LaTeX 命令名；星号形式自动兼容。

引用查询不是额外设置项。1.0.0 固定搜索 citation key、标题、作者、年份、DOI 和 ISBN，不搜索期刊/出版物、摘要、标签或笔记，也不做拼写纠错。多词先规范化、去重，再按 AND 跨字段匹配；排序依次偏好精确原始 key、紧凑 key/前缀、精确 DOI/ISBN、全词/词首和普通子串，相关度相同时才偏好 bibliography 来源。TeXLeaf 对 bibliography 与 Zotero 全库快照本地匹配、排序后，最多把 100 条交给原生 Suggest；继续输入会针对全库重新计算，而不会受上一轮前 100 条限制。键入每个字符不会请求 Zotero；首次加载、缓存过期、相关设置变化或手动刷新才更新本地快照。

示例：

{
  "texleaf.bibliographyFile": "bib/sources.bib",
  "texleaf.bibliographyFormat": "biblatex",
  "texleaf.citationCommands": [
    "cite", "parencite", "textcite", "smartcite"
  ],
  "texleaf.zoteroLibrary": "42",
  "texleaf.zoteroPort": 23119,
  "texleaf.zoteroCacheSeconds": 60
}

远程主机、Better BibTeX、去重和第三方 citation provider 的边界见 文献与 Zotero。

TeXLeaf · AI 写作

AI 写作支持 DeepSeek 官方/自定义 Chat Completions 与 OpenAI 官方/自定义 Responses 两个 Provider，使用用户自己的 API Key，安装后默认关闭。即使子功能默认是 true，在总开关、当前 Provider/规范化接收地址的正文传输 consent、workspace trust 和对应 SecretStorage Key 全部齐备前也不会联网。ChatGPT Plus/Pro/Codex 订阅不等于 OpenAI API 额度。

设置	默认值 / 范围	作用
texleaf.aiWriting.enabled	false	AI 写作总开关；未信任工作区中仍强制停用
texleaf.aiWriting.automaticReview	true	总开关开启后，停止键入时自动局部检查本次改动的正文句子
texleaf.aiWriting.inlineCompletions	true	总开关开启后，提供 AI 词语和句子行内补全
texleaf.aiWriting.provider	deepseek；deepseek / openai	使用 DeepSeek Chat Completions，或 OpenAI Responses 服务
texleaf.aiWriting.deepseekModel	deepseek-v4-flash；deepseek-v4-flash / deepseek-v4-pro	DeepSeek 模型；flash 优先低延迟/低成本，pro 优先质量
texleaf.aiWriting.deepseekBaseUrl	https://api.deepseek.com	DeepSeek Chat Completions Base URL；请求目标为规范化后的 {Base URL}/chat/completions
texleaf.aiWriting.openaiModel	gpt-5.6-luna；1–128 字符	OpenAI Responses 模型 ID；允许字母、数字、点、下划线、冒号、斜杠和连字符
texleaf.aiWriting.openaiBaseUrl	https://api.openai.com/v1	Responses Base URL；TeXLeaf 请求规范化后的 {Base URL}/responses
texleaf.aiWriting.language	auto；auto / english / chinese	自动识别、英语论文检查（中文解释）或中文学术写作检查
texleaf.aiWriting.style	academic；academic / general / concise	学术、通用或简洁写作目标
texleaf.aiWriting.reviewDelayMs	900，500–10000	停止键入后，多久调度改动句子的自动检查
texleaf.aiWriting.completionDelayMs	500，100–5000	自动行内补全请求前的额外等待时间
texleaf.aiWriting.maxParagraphLength	6000，500–20000	单个自动检查句子或手动正文段最多发送的 UTF-16 字符数；设置名为兼容旧配置而保留
texleaf.aiWriting.maxDocumentLength	30000，1000–100000	一次手动整篇检查最多发送的正文 UTF-16 字符数

费用敏感的配置示例：

{
  "texleaf.aiWriting.enabled": true,
  "texleaf.aiWriting.automaticReview": false,
  "texleaf.aiWriting.inlineCompletions": false,
  "texleaf.aiWriting.provider": "deepseek",
  "texleaf.aiWriting.deepseekModel": "deepseek-v4-flash",
  "texleaf.aiWriting.deepseekBaseUrl": "https://api.deepseek.com",
  "texleaf.aiWriting.language": "english",
  "texleaf.aiWriting.style": "academic",
  "texleaf.aiWriting.maxParagraphLength": 3000,
  "texleaf.aiWriting.maxDocumentLength": 12000
}

DeepSeek 自定义 Base URL 只使用 {Base URL}/chat/completions 与 JSON Output；OpenAI 自定义 Base URL 只使用 {Base URL}/responses 与 TeXLeaf 的 Structured Outputs 契约。两个 Provider 不会跨协议回退。远程地址必须是 HTTPS；只有 localhost、127.0.0.1、[::1] 允许 HTTP。URL 禁止用户名、密码、查询参数、fragment、主机名尾随点，路径也不能已经以对应的 /chat/completions 或 /responses endpoint 结尾；请求不会跟随 HTTP 重定向。官方说明见 DeepSeek 的 Create Chat Completion 与 JSON Output，以及 OpenAI 的 Responses API 与 Structured Outputs。

API Key 不属于设置项：它只通过密码输入框保存到当前扩展环境的 SecretStorage，不写入 settings.json，也不随普通 Settings Sync 跨设备同步。每个规范化 DeepSeek/OpenAI Base URL 分别保存 Key 和 consent；默认 https://api.deepseek.com 继续兼容旧版本的 v1 DeepSeek Key/consent，但任何自定义 DeepSeek 地址都使用新的目标专用记录并且绝不复用官方凭据。OpenAI 各地址以及两个 Provider 之间同样互相隔离。全部 14 个普通 AI 设置可以按用户/Profile 配置同步，但另一台设备仍需单独确认和设置 Key。OpenAI 请求包含 store:false，这只是客户端请求；自定义服务的实际存储、训练、计费与隐私政策由其运营方负责。允许联网的 URI、正文 allowlist/fail-closed 遮罩、编辑器装饰线/专用 Hover/Quick Fix、改写、行内补全、费用与隐私边界见 AI 写作助手。

自动检查使用防抖、取消和同版本同句子去重，不是每按一个键都发起网络请求。每批最多处理 8 个改动句子，每个文档版本最多自动请求 64 个不同句子；没有 pending 改动句子时，纯光标导航才选择附近句子。中文 。！？ 无需句间空格，句末中英文引号/括号归入前句。手动多段选区或整篇检查每次最多 32 个正文段，并同时受单段和总字符上限约束。

一次可精确重建的文本事务会把相关旧句与新句并集作为 provider 的完整上下文，但问题失效仅依据实际编辑与累计 pending 的精确 UTF-16 范围。句号/空行 split 或 merge、同一事务多处编辑和零宽边界都会把关联句子加入 pending；与局部范围不相交的同句问题在 exact original、strict remap 与 editable prose 都成立时继续保留。自动回应只替换命中 dirty range 或与新问题相交的旧项，手动段落/全文则仍刷新检查范围。保存等空 change 不清结果。每句成功立即合并；同批后续 API 失败不会回滚前句，剩余句子会在活动栏明确显示“等待局部复检”。由于服务商网络延迟、频率限制和 API 费用，这仍是近实时而非无延迟的本地检查。

TeXLeaf 不包含或播放音频，也不发布 AI 原生 Diagnostic。问题用编辑器装饰线标出，专用 Hover 显示一份类别、中文 message/explanation、替换预览与“应用这条建议”；活动栏问题树显示真实严重性，灯泡 Quick Fix 仍可应用/忽略。Hover 只信任白名单中的 TeXLeaf 内部应用命令，模型文字不能生成可执行命令；点击链接后仍会在后端重新验证当前文档版本、问题身份、范围、exact original 与 editable prose。AI 问题不会进入 Problems，不会形成重复 Hover 或触发 Error/Warning accessibility signal；点击树条目只滚动到范围，不移动主光标。数学内容则用不可编辑的等长语义占位符替代，公式源码不发送，Take 后的 display formula 会作为语法宾语而不是缺失上下文；replacement 保持正文原语言。

Windows 微软拼音在中文模式下会优先使用 Ctrl+. 切换中英文标点；按键没有到达 VS Code 时不会打开 Quick Fix。可以按 Shift 切换到英文输入模式后再使用 Ctrl+.，或通过 F1 / Command Palette、右键菜单、灯泡及 Hover 的“应用这条建议”操作。0.8.9 不新增专用快捷键，也不修改用户的输入法或键位设置。

增量重映射已证明未受影响的问题会保留稳定 lineage ID，同时更新当前 fingerprint、文档版本、范围和 UTF-16 offset。已渲染的树节点或 Quick Fix 因而不会仅因前方文字改变导致的安全平移而误报过期；每次应用仍重新验证 exact original、当前范围和 editable prose。真正失效的旧节点会刷新树、装饰线与状态，并只在状态栏短暂提示，不弹信息通知，也不播放音效。“应用全部”在确认后按捕获的稳定 ID 从最新安全状态重新解析建议；等价 state 对象刷新不会误失败，正文版本已变、任一捕获问题已移除/失效/无法唯一解析，或者范围、原文或重叠校验失败时仍整批停止。确认后才出现的其他问题不会被纳入本批修改。

校验后的问题会在当前 Profile/扩展宿主的私有 globalStorage 跨关闭文档和 VS Code 重启恢复；它不写工作区、不随 Settings Sync 同步，也不保存论文全文。只有完整源码 UTF-16 长度与 SHA-256 和快照完全一致时才按原 offset 逐条复核 original 与 editable prose；外部改动、hash/长度不匹配或单条验证失败会 fail closed 丢弃并要求重检，不跨源搜索相同短语。单文档最多 2048 条、单记录 2 MiB，每 Profile 最多 256 个文档记录和 32 MiB；pending、请求状态与本次会话忽略不持久化。详细格式和清除语义见 AI 写作助手。

TeXLeaf · 预览

设置	默认值 / 范围	作用
texleaf.mathPreview.enabled	true	Math Preview 总开关
texleaf.mathPreview.presentation	"cursor"	cursor、hover 或 both
texleaf.mathPreview.placement	"autoBelow"	autoBelow 优先下方，autoAbove 优先上方；首选侧不足时尝试另一侧，上下都不足时都强制使用上方，并对超高、多行公式保留公式尾部；above / below 固定方向。旧值 auto 仍按 autoBelow 运行，但不在设置选项中显示
texleaf.mathPreview.debounceMs	120，50–2000	输入/移动停止后的更新延迟；大文档至少 300 ms
texleaf.mathPreview.scale	1，0.5–3	SVG 显示缩放
texleaf.mathPreview.maxSourceLength	8192，256–32768	单公式最大 UTF-16 字符数
texleaf.mathPreview.macros	{}	最多 128 个安全 MathJax 宏

宏键不带反斜杠，只允许 [A-Za-z@]+；单个 replacement 最多 2,048 字符，设置序列化总长度最多 16,384 UTF-16 字符。示例：

{
  "texleaf.mathPreview.presentation": "cursor",
  "texleaf.mathPreview.placement": "autoBelow",
  "texleaf.mathPreview.debounceMs": 180,
  "texleaf.mathPreview.scale": 1.1,
  "texleaf.mathPreview.macros": {
    "RR": "\\mathbb{R}",
    "CC": "\\mathbb{C}"
  }
}

定位、主题、性能和 API 限制见 Math Preview。

cursor 与 both 采用 last-known-good / stale-while-revalidate：防抖和后台渲染期间保留上一张有效预览，通过单一稳定 decoration 原位更新；临时失败有 750 ms 宽限，Hover SVG 仅在真正请求 Hover 时写盘。离开公式、禁用、Dismiss 或停在无效状态超过宽限仍清理旧卡片。hover 继续遵循 VS Code 原生 Hover 生命周期，输入时可能由编辑器关闭。

placement=autoBelow 是默认的“自动（优先下方）”：下方能完整容纳时使用下方，否则改到上方。placement=autoAbove 是“自动（优先上方）”：上方能完整容纳时使用上方，否则改到下方。上下都不足时，两种自动模式都强制使用上方并共用超高、多行公式的末尾保留策略；需要固定方向时显式选择 above 或 below。升级前已经写入的旧值 auto 仍会在运行时按 autoBelow 解释，但新的设置 UI 不再提供这个旧名称。

语言默认值与第三方补全

TeXLeaf 为 LaTeX/TeX 贡献以下默认值：

"[latex]": {
  "editor.wordBasedSuggestions": "off"
},
"[tex]": {
  "editor.wordBasedSuggestions": "off"
}

作用是避免 VS Code 把文档中出现过的普通单词或 citation key 再作为 Text/word 候选混入 Suggest。用户或工作区显式设置优先于扩展默认。

这不能删除 LaTeX Workshop 自己的 citation provider。若它继续用 key 作为标签，可由用户显式设置：

{
  "latex-workshop.intellisense.citation.label": "title"
}

TeXLeaf 不能选择性删除另一扩展的候选；不要设置 editor.suggest.showReferences: false，否则会同时隐藏 TeXLeaf 文献和其他 Reference 补全。详见 文献与 Zotero。

命令

片段

命令面板名称	Command ID
TeXLeaf: 管理 Snippet 与模板	texleaf.openSnippetEditor
TeXLeaf: 管理 TeX 模板	texleaf.openTemplateFile
TeXLeaf: 打开高级 Snippet JSONC	texleaf.openSnippetFile
TeXLeaf: 恢复默认片段	texleaf.restoreDefaultSnippets
TeXLeaf: 重载片段	texleaf.reloadSnippets
TeXLeaf: 搜索并插入片段	texleaf.pickSnippet
TeXLeaf: 导入片段	texleaf.importSnippets
TeXLeaf: 导出片段	texleaf.exportSnippets
TeXLeaf: 用片段包裹所选内容	texleaf.wrapSelection
TeXLeaf: 切换启用状态	texleaf.toggle

文献

命令面板名称	Command ID
TeXLeaf: 显示参考文献补全	texleaf.pickCitation
TeXLeaf: 刷新 Zotero 参考文献缓存	texleaf.refreshZotero

AI 写作

命令面板名称	Command ID
TeXLeaf: 切换 AI 写作助手	texleaf.aiWriting.toggle
TeXLeaf: 设置当前 AI 服务商 API Key	texleaf.aiWriting.setApiKey
TeXLeaf: 清除当前 AI 服务商 API Key	texleaf.aiWriting.clearApiKey
TeXLeaf: AI 检查当前段落或选区	texleaf.aiWriting.reviewParagraph
TeXLeaf: AI 检查当前文档	texleaf.aiWriting.reviewDocument
TeXLeaf: 显示 AI 写作问题列表	texleaf.aiWriting.showIssues
TeXLeaf: 应用当前全部 AI 建议	texleaf.aiWriting.applyAll
TeXLeaf: AI 改写选区或当前句	texleaf.aiWriting.rewriteSelection
TeXLeaf: 触发 AI 行内补全	texleaf.aiWriting.triggerCompletion
TeXLeaf: 清除 AI 写作问题	texleaf.aiWriting.clearDiagnostics

预览

命令面板名称	Command ID
TeXLeaf: 切换 Math Preview	texleaf.toggleMathPreview
TeXLeaf: 刷新 Math Preview	texleaf.refreshMathPreview
TeXLeaf: 关闭当前 Math Preview	texleaf.dismissMathPreview

部分内部命令（如 texleaf.handleTab、matrixEnter）由 when context 和键位调用，不需要直接从命令面板运行。

默认快捷键

功能	Windows / Linux	macOS	说明
搜索并插入片段	Ctrl+Alt+L	Cmd+Alt+L	编辑器聚焦且 TeXLeaf 开启
精确展开 / Tabout / Matrix 列	Tab	Tab	精确 trigger / 活动 tabstop 优先；当前 cell 有真实 Tabout 目标就跳出，否则按 Suggest 或 Matrix 上下文接受补全/插列
Matrix/Align 换行	Enter	Enter	只在 TeXLeaf 提供对应 action 时
跳出 Matrix/Align	Shift+Enter	Shift+Enter	当前 matrix action 可用时
手动空格展开	Space	Space	manualTrigger=space 时
删除空数学定界符	Backspace	Backspace	光标位于受支持空定界符内部
关闭当前预览	Escape	Escape	Suggest/Rename/Inline Suggest 不活跃时

快捷键冲突可在 Preferences: Open Keyboard Shortcuts 搜索 texleaf，或运行 Developer: Toggle Keyboard Shortcuts Troubleshooting。

用户设置、工作区设置与安全

• 个人输入习惯适合用户设置；
• bibliography 路径、citation commands 和项目附加 Snippet 适合工作区设置；
• 不应把个人 Zotero library 名称或不必要的本机端口写进公开仓库；
• 未信任工作区忽略 snippetFiles，并禁用 Zotero 读取/写入；
• bibliographyFile 只接受工作区内相对 .bib 路径；
• zoteroPort 只改变固定回环主机上的端口数字。
• AI 写作默认关闭；未信任工作区、Untitled、.bib 和非 file:/vscode-remote: URI 不会发送正文；已有路径的 .tex 可能发送尚未落盘的当前编辑器内容；
• 全部 14 个 AI 普通设置只能放在用户/Profile 层，可随普通 Settings Sync 同步；工作区和 .vscode/settings.json 不能开启、重定向、换模型或改变费用相关限制；
• AI Key 只保存在 SecretStorage，不应放入任何用户/工作区设置，也不会通过普通 Settings Sync 同步；每个规范化 DeepSeek/OpenAI Base URL 的 Key/consent 互相隔离，只有默认 DeepSeek 官方地址兼容其旧 v1 记录；
• 自动检查与行内补全都会产生 API 请求和可能的费用；需要严格控制时关闭子功能或总开关；
• AI 建议只通过结构与范围安全校验，不代表语义或事实必然正确。模型 offset 可按 UTF-16、Unicode code point、UTF-8 byte 或 CRLF 换行计数解释，但 TeXLeaf 只接受非空 original 的无歧义逐字映射；不会通过 Unicode/空白归一化或模糊匹配猜测位置。单条坏建议会被丢弃，不影响独立且不重叠的有效项。完整边界见 AI 写作助手。

相关页面

• 片段与模板
• Snippet 格式
• AI 写作助手
• 文献与 Zotero
• Math Preview
• 故障排查
• 首页