Troubleshooting

故障排查

本页按“片段、AI 写作、文献、预览”四部分排查 TeXLeaf 0.8.11。多数问题可以通过确认文件作用域、设置覆盖、工作区信任、第三方扩展和 Output → TeXLeaf 日志定位。

先做这六步

1. 确认安装的是 Marketplace 中的 zhangxh-math.texleaf，或 GitHub Release 中对应版本的 VSIX，不是旧本地构建。
2. 运行 Developer: Reload Window。
3. 在 Settings 搜索 @ext:zhangxh-math.texleaf，检查目标功能总开关。
4. 检查设置右侧齿轮的“Modified in”来源；工作区/语言设置可能覆盖用户设置。
5. 打开 View → Output，选择 TeXLeaf，复现一次问题。
6. 若怀疑扩展冲突，在临时 Profile 或通过 Help: Start Extension Bisect 比较。

不要在含未保存工作时随意删除 Profile/globalStorage。管理器和恢复命令已经提供冲突检查与备份。

片段没有展开

依次检查：

• 文件是否已经保存；
• 后缀是否正好是 .tex 或 .bib，而不是 Untitled、.md、.tex.md；
• 右下角 language mode 是否在 texleaf.languageIds，默认 latex、tex、bibtex；
• texleaf.enabled 是否为 true；
• 自动规则需要 texleaf.autoSnippets=true；
• 非自动规则需要按 texleaf.manualTrigger 对应的 Tab 或 Space；
• t/m/M/n 是否符合当前位置的文本、行内数学或块级数学；
• 当前环境是否在 texleaf.excludedEnvironments；
• “问题”面板是否有 JSONC、正则、选项或占位符诊断。

对于 dm、\thm、\dfn、\lem、\cor 和四个模板，即使自动事件偶发被输入法或 Suggest 打断，完整输入 trigger 后按 Tab 应走 TeXLeaf 精确兜底。

;a 在 equation 里不展开

如果位置在以下参数中，这是预期保护：

\label{;a}
\tag{;a}
\tag*{;a}

闭合参数后，外层数学环境会恢复。如果在普通公式正文仍不展开，检查是否处于注释、verb/verbatim 或被排除环境。

\thm 在 Suggest 中不是第一项

出厂 \thm 是自动规则，通常完整输入即展开；Tab 精确兜底不依赖普通 Suggest 排名。若只看到 LaTeX Workshop 的命令候选：

• 确认没有关闭 texleaf.autoSnippets；
• 确认当前是文本模式；
• 在管理器中检查 environment.theorem 是否启用、trigger 是否被自定义；
• 按 Tab 验证 exact path；
• 在快捷键页检查 Tab 是否被其他扩展更高优先级接管。

dm 有时自动、有时不自动

dm 使用文本模式和词边界。它不会在较长单词内部、数学区域、Untitled 或不受支持文件中展开。中文输入法 composition 期间，扩展会避免对尚未提交的组合文本重复处理；提交完成后如仍未展开，按 Tab，并附最小复现报告。

公式末尾按 Tab 却插入了 Suggest 片段

先确认扩展详情显示 0.8.11 并 Reload Window。自 0.8.10 起只向原生 Suggest 返回具有非空 trigger 前缀匹配的 TeXLeaf 片段：例如输入 + 时可以出现 +-，继续输入为 +1 后该条目应被移除。完全无关的 +-、sq 等条目仍停留时，先关闭其他扩展比较；VS Code 会合并所有 Completion Provider，TeXLeaf 无法删除 LaTeX Workshop 等扩展返回的候选。

默认开启 Tabout 时，Suggest 打开后按 Tab 的预期决策是：精确 TeXLeaf trigger 兜底优先；否则，当前位置实际存在右括号、\rangle 或数学结束分隔符时执行 Tabout，没有真实跳出目标时接受当前选中的原生补全。数学区域的活动 Snippet Session 若仍有下一 tabstop，会先关闭 Suggest、再前往该占位符；Inline Suggest、Rename 输入框和 Matrix action 会排除 Suggest/Tabout 绑定，继续使用原来的 Tab 优先级。需要绕开当前输入浏览当前上下文可直接插入的普通片段时使用 Ctrl+Alt+L（macOS 为 Cmd+Alt+L）。

自动分数、括号与 Matrix

(sum) 展开后光标跑到 \right) 外

先确认扩展详情显示 0.8.11 并 Reload Window。当前版本对没有显式 tabstop 的普通片段，会在自动放大整个括号范围后恢复相对光标：(sum) 应得到 \left(\sum|\right)。继续输入 +、上下标等内容应留在括号内；当当前位置没有精确手动片段 trigger 时，按一次 Tab 才跳到 \right) 之后。刚停在 \sum 后直接按 Tab 会优先展开既有 sum-limits 手动片段，这是预期优先级。片段本身已有 tabstop 时继续遵守它的占位符顺序；如果仍直接落到外侧，请记录最小片段定义、输入前后的源码和是否存在其他活动 Snippet Session。

1/2 没变成分式

• 需要数学区域；
• texleaf.autoFraction=true；
• 输入第一枚 / 后保留 1/ 是正常的，首个有效分母字符 2 到来时才变换；
• 左侧扫描遇到 autoFractionBreakingCharacters 会停止；
• // 是另一条明确 Snippet，输入第二个 / 应优先展开空分式。

Enter/Tab 被其他扩展接管

1. 在 Keyboard Shortcuts 搜索 texleaf、tab、enter；
2. 运行 Developer: Toggle Keyboard Shortcuts Troubleshooting；
3. 确认 texleaf.matrixShortcuts=true；
4. 检查环境是否在 texleaf.matrixEnvironments；
5. 暂时停用 LaTeX Workshop 等扩展比较；
6. 注意 Tab 先处理活动 snippet tabstop，再执行列操作。

left/right 智能 Enter 只处理唯一、顶层、安全配对。遇到嵌套 pair、&、已有 \\、命令参数、注释或嵌套环境时回退普通行为是设计选择。

管理器问题

一直显示“正在载入”

• 升级到当前 0.8.11；
• 运行 Developer: Reload Window；
• 打开 Developer: Toggle Developer Tools，查看 Webview CSP/脚本错误；
• 检查 Profile 是否允许扩展 globalStorage 写入；
• 暂停同步后重试，排除另一个窗口持续修改；
• 不要把旧版全局 JSONC 的 JavaScript/函数格式直接粘入结构化数据。

管理器的 ready 握手会重试，主机加载和消息有边界；正常库不应永久 busy。

保存提示 revision/并发冲突

这表示管理器载入后，另一个窗口、高级 JSONC、Settings Sync 或恢复操作修改了同一库。正确处理：

1. 复制尚未保存的重要草稿；
2. 选择重新载入当前磁盘/Profile 内容；
3. 重新应用变更；
4. 再保存。

不要通过反复点击保存绕过 CAS。冲突拒绝是在保护另一个窗口的修改。

批量替换结果不对

• 先检查选中的字段范围；
• 正则模式下 replacement 使用 JavaScript 字符串替换语义，但数据仍不可执行脚本；
• 关闭正则时，查找内容按字面量处理；
• 看预览中的 before/after 与数量；
• 应用后仍是草稿，可先撤销再保存；
• 大规模操作前先导出备份。

恢复默认后自定义丢失

恢复默认会明确替换当前工厂库，但成功前应创建原字节备份。到当前扩展宿主的 globalStorageUri/backups 中恢复，或从先前导出文件导入。不要从另一 Profile 猜路径；先确认 Stable/Insiders、本地/Remote 和 Profile。

模板不展开

四个模板要求：

• 已保存的 .tex；
• 单光标；
• 文档除空白和完整 trigger 外无其他内容；
• 自动展开需 autoSnippets=true，否则按 Tab。

若修改 trigger 后旧 trigger 仍生效：

• 确认管理器右上角已保存且无错误；
• 重新选择该模板检查值；
• 搜索是否另有同 trigger Snippet；
• Reload Window 后复试；
• 确认当前 Profile 与修改时相同。

article 模板参考文献样式应是 alpha。Beamer 中的 \theoremstyle{plain} 是定理样式，不是 bibliography style。

Settings Sync 问题

• Settings Sync 必须在 VS Code 账户中主动开启；
• 手工 VSIX 不会自动安装到另一设备；先安装相同 extension ID 的兼容版本；
• 同步检测不是实时，通常等窗口重新聚焦或下一轮约 15 秒检查；VS Code 云端传播另计；
• envelope 超过 256 KiB、库无效或 dirty 时暂停同步；
• Profile、Stable/Insiders、本地/Remote 可能是独立副本；
• 双方都改动时会提示冲突，不会自动选“最新时间”。

\cite{} 没有文献

检查：

• 当前工作区是否信任；
• .tex 是否已保存；
• texleaf.enabled、texleaf.zoteroCitations；
• 命令是否在 texleaf.citationCommands；
• 光标是否真的在必需大括号内，而不是可选参数或命令外；
• bibliographyFile 是否指向当前 workspace root 内的 .bib；
• .bib 是否存在未闭合外层条目或重复 key；
• 手动运行 TeXLeaf: 显示参考文献补全。

即使 Zotero 不可用，合法的已有 bibliography 条目仍应出现。

Zotero 没有候选或连接失败

1. 启动 Zotero，并等待主窗口完全加载；
2. 确认允许本机其他应用通信；
3. 默认端口 23119，Juris-M 常见 24119；
4. 检查 zoteroLibrary 名称，重名群组库改用数字 ID；
5. 运行 TeXLeaf: 刷新 Zotero 参考文献缓存；
6. 查看 Output 中是 connection、404、timeout、library-not-found、RPC 还是 invalid-response；
7. Better BibTeX 不可用时，确认 Zotero 官方 Local API 可用；
8. Flatpak/Snap/安全软件可能隔离回环连接。

不要把端口改成公网转发，也不要尝试配置远程主机；TeXLeaf 固定 127.0.0.1。

Remote/WSL/SSH/Container

127.0.0.1 指扩展宿主所在网络命名空间。确认 TeXLeaf 安装在本地 UI 一侧；若它只安装/运行在 Remote，则端口指远程机器/容器，本机 Zotero 不可达。Codespaces 浏览器环境不能假设访问桌面 Zotero。

更多边界见 文献与 Zotero。

仍然出现 citation key 候选

先区分来源：

• abc/Text 类型普通文档单词：TeXLeaf 已为 [latex]/[tex] 默认设置 editor.wordBasedSuggestions=off；检查用户/工作区是否显式覆盖。
• Reference 类型、逐条来自 .bib 的 key：很可能是 LaTeX Workshop 自己的 citation provider，不是 TeXLeaf。

TeXLeaf 不能从 VS Code 合并后的列表中删除另一个扩展的候选。可让 LaTeX Workshop 改用标题标签：

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

不要用 editor.suggest.showReferences=false，它会同时隐藏 TeXLeaf citation 和 \ref 等 Reference 补全。完整解释见 文献与 Zotero。

Zotero 导入失败或重复

• 导出格式必须是 bibtex 或 biblatex；
• .bib 未闭合、重复 key 或 key 被不同文献占用时会停止；
• DOI/ISBN/标题/第一作者/年份不足会降低跨 key 去重能力；
• dirty bibliography 不自动保存是保护行为；
• 提交前当前 citation/文档版本改变会取消；
• Better BibTeX 返回多个条目或 key 不一致会拒绝；
• 查看 Output 的明确错误，不要手工重复点击导入多次。

AI 写作助手

AI 写作默认关闭，而且比普通片段有更严格的运行范围。先检查：

• 当前是受信任工作区中已有文件名和路径的 .tex；发送的是当前编辑器内容，可能包含尚未落盘的编辑；
• URI 是本地 file: 或 Remote/WSL/Dev Container 的 vscode-remote:；
• language ID 是 latex 或 tex；
• texleaf.enabled=true 且 texleaf.aiWriting.enabled=true；
• 已经确认当前 Provider/规范化接收地址的正文传输提示；
• texleaf.aiWriting.provider、对应模型和该 Provider 的 Base URL 有效；
• 当前运行 TeXLeaf 的扩展环境已经为当前 Provider/规范化 Base URL 设置专用 API Key；
• 当前文字属于正文 allowlist，而不是数学、注释、citation、label、URL、代码或未知 TeX 结构；
• Output → TeXLeaf 中没有认证、余额、限流、网络、超时或无效响应错误。

.bib、Untitled、Git/其他虚拟文档和未信任工作区不会发送正文。这是安全边界，不是故障。完整说明见 AI 写作助手。

已开启，但没有自动检查

• texleaf.aiWriting.automaticReview 必须为 true；
• 停止键入后等待 reviewDelayMs；默认 900 毫秒，可设置为 500–10000 毫秒；
• 继续输入会取消旧请求并重新计时；本次编辑涉及的句子优先进入局部复检队列，没有 pending 改动时纯光标导航才会选择附近句子；
• 自动模式每批最多处理 8 个改动句子，不会后台扫描整篇论文；同一文档版本、同一句子和相同 AI 配置会去重，每版本最多自动请求 64 个不同句子；
• 单个句子或手动正文段超过 maxParagraphLength 时不会发送；
• 只有受保护 TeX、数字符号或空白的段落不会形成正文请求；
• 运行 TeXLeaf: AI 检查当前段落或选区 可区分防抖问题与 API 问题。

自动检查不是每按一个键就请求一次：防抖、取消和去重会合并连续操作。服务商网络延迟、处理时间、频率限制与 API 费用仍然存在，所以反馈只能是近实时；不要用本地拼写器的无延迟表现作为故障判断标准。

API Key 无效或没有权限

运行 TeXLeaf: 设置当前 AI 服务商 API Key 重新输入。DeepSeek 官方/自定义 Chat Completions 地址与 OpenAI 官方/自定义 Responses 地址都需要当前目标认可的 API Key。ChatGPT Plus/Pro/Codex 订阅不等于 OpenAI API 额度，也不能授权 DeepSeek。Key 不在 settings.json 中，也不会通过普通 Settings Sync 同步；不同电脑、Profile、Stable/Insiders、本地/Remote 环境可能需要分别设置。

DeepSeek 与 OpenAI Key/consent 都按规范化 Base URL 隔离。默认 https://api.deepseek.com 继续兼容旧版本的 v1 DeepSeek 记录，但任意自定义 DeepSeek 地址都使用新的目标专用记录，不会复用官方 Key；OpenAI 官方与代理地址、两个 Provider 之间也不复用。切换主机、端口或路径后，需要为新目标重新确认并设置 Key。若状态栏仍显示 Key 图标，先检查当前 Provider/Base URL 是否就是设置 Key 时的目标。

全部 14 个 texleaf.aiWriting.* 普通设置都是 application 级用户/Profile 配置，可以随 VS Code Settings Sync 同步；工作区、工作区文件夹和 .vscode/settings.json 不能开启 AI、重定向 Base URL、切换 Provider/模型，或改变防抖和发送长度。若项目设置看似“没有生效”，这是有意的安全边界，不是配置读取故障。

不要把 Key 粘贴到 Issue、Output、截图或任何项目文件。

“AI 写作配置、模型名称、自定义 Base URL 或发送内容不符合安全限制（language-too-long）”

如果该通知来自 0.8.5，这不是 Key、余额、Base URL、模型或论文正文过长。0.8.5 的控制器误把完整的输出语言说明当作 language 协议标签；字符串超过两个客户端共同执行的 64 字符上限，于是请求在 fetch 之前被本地拦截。DeepSeek/OpenAI 的官方与自定义地址都会受影响，自动句子检查、手动段落/选区检查、整篇检查、改写和行内补全也使用了同一错误参数。

升级到当前 0.8.11 并运行 Developer: Reload Window。自 0.8.6 起，三个设置值会固定映射为短标签：auto → auto、english → English、chinese → Chinese；需要显示给作者的 message/explanation 仍由 system prompt 要求使用简体中文，replacement 仍保持论文原语言。无需因此重新充值或更换 Key；旧版被本地拒绝的尝试没有发出 HTTP 请求，也不会产生该次 API 费用。

0.8.11 仍有意保留客户端边界：直接注入超过 64 字符、含换行或控制字符的语言标签会在联网前失败。升级后若设置页仍显示旧版或继续得到相同错误，检查是否仍启用了旧 VSIX，确认扩展详情版本后重新 Reload Window。

余额、限流、网络或超时

• 余额/计费不足：到当前 Provider/自定义服务控制台检查 API 账户；TeXLeaf 不读取余额；
• 请求过于频繁：稍后重试，提高防抖时间，或关闭自动检查/行内补全；
• 网络/超时：确认实际运行扩展的本地或 Remote host 可以访问当前 endpoint；DeepSeek 是规范化 Base URL 下的 /chat/completions，OpenAI 是规范化 Base URL 下的 /responses；
• Remote/WSL/SSH/Container 的代理、防火墙和证书配置可能与桌面本机不同；
• DeepSeek 自定义 Base URL 只兼容 Chat Completions + JSON Output；OpenAI 自定义 Base URL 只兼容 Responses + Structured Outputs，两个 Provider 不会跨协议回退；
• 远程 Base URL 必须是 HTTPS，只有 localhost、127.0.0.1、[::1] 允许 HTTP；包含用户信息、查询、fragment、主机名尾随点，或路径已以对应 /chat/completions//responses endpoint 结尾的 Base URL 会被本地拒绝，请求也不会跟随 HTTP 重定向。

DeepSeek 错误解释见 DeepSeek API Error Codes，价格见 DeepSeek Models & Pricing。OpenAI 错误解释见 OpenAI API Error Codes，Responses 契约见 Responses API。

返回空白、无效 JSON 或被截断

这类结果不会自动修改原文。DeepSeek 仅在响应为空或 JSON 语法无效时自动重试一次；schema、字段、offset、原文或范围校验失败不会重试。DeepSeek 解析器只接受纯 JSON，或完整包住全部响应的单层 json fence；说明文字、多个/嵌套/不完整 fence 都会失败。缩小选区、减少单段长度、稍后重试；若持续出现，只记录日志中的安全错误子码和匿名化最小示例，不要粘贴原始响应。模型结果还必须通过 offset、original、可编辑范围、重叠与 TeX 控制字符校验，因此“API 成功”也不保证每条建议都会进入 TeXLeaf 装饰线、专用 Hover 与问题树。

模型被要求返回零基 UTF-16 offset，但有些模型或兼容接口会按 Unicode code point、UTF-8 byte，或者把 CRLF 当成一个换行计数。TeXLeaf 会尝试这些有限解释，并只接受非空 original 的无歧义逐字位置；如果 original 在正文中重复且坐标不能消除歧义，或只有经过 Unicode、引号、大小写、空白/换行归一化才相似，就会丢弃建议而不猜测。请求协议要求模型用相邻不变原文作非空插入锚点，并在 replacement 中保留该锚点；本地验证 exact 非空锚点，但不会错误地要求每个普通替换都包含 original。

常见安全子码：empty-content 和 invalid-json-output 会各自触发最多一次自动重试；content-too-large、invalid-issues、invalid-original、invalid-issue-offset、issue-original-not-found、issue-location-ambiguous、duplicate-issue、overlapping-issues、http-body-too-large 都不会自动重试。顶层结构失败时整批拒绝；单条无效建议只丢弃该条，真正相交的冲突组整组丢弃，完全相同的重复项去重保留一条，其他独立有效项继续显示。子码含义与完整安全边界见 AI 写作助手。

OpenAI 返回 refusal、incomplete、空 output、schema 不兼容或 Structured Outputs 不受支持时也会 fail closed。自定义服务收到 store:false 只是请求字段；它是否实际保留或训练数据由运营方政策决定。

“42 条可审阅，另安全忽略 20 条”

这不是 API Key、余额、认证或网络失败。它表示模型已经返回候选，其中 42 条被 TeXLeaf 精确、无歧义地映射到当前原文；另外 20 条因为完全重复、范围重叠、字段不安全、找不到原文或无法唯一定位而按 fail-closed 原则丢弃。被忽略的候选不会修改原文，也无需因为这个计数重设 Key 或充值。

点击状态栏 TeXLeaf AI，或运行 TeXLeaf: 显示 AI 写作问题列表，可以在活动栏查看 42 条可审阅项、当前检查状态和不含论文正文的安全忽略摘要。列表按行号显示类别、真实严重性、原文 → 替换 和解释；点击条目会滚动到对应范围，并用主题自适应背景与轮廓标出当前问题，其他问题继续保留下划线，但不会移动主光标。使用上下文菜单可以应用或忽略单条建议；批量应用必须经过确认和整批重新校验。

检查完成或点击问题时听到声音

TeXLeaf 不包含音频文件，也不会主动播放检查音效。自 0.8.7 起，AI 问题不发布为 VS Code 原生 Diagnostic：编辑器只画无音频装饰线，详情由 TeXLeaf 专用 Hover 和活动栏问题树提供，Quick Fix 仍会严格校验。AI 问题因此不会进入 Problems、形成重复原生 Hover，或触发 Error/Warning marker 的 accessibility signal；点击树条目只会滚动并显示主题自适应的选中背景与轮廓，不移动主光标，也不会因为这层高亮触发诊断音效。高亮会沿稳定 issue lineage 跟随无关前文编辑，并在应用、忽略、清除、失效或关闭 AI 后自动消失。

升级并 Reload Window 后如果仍有声音，先确认没有旧 TeXLeaf VSIX 同时启用，再检查 VS Code 的 accessibility.signals.* 设置和其他诊断扩展。TeXLeaf 不会替用户全局关闭这些辅助功能，因为那会同时影响其他语言和扩展的有效提示。

装饰线、Hover、Quick Fix 或活动栏列表不出现

• 手动检查可能确实没有发现可安全映射的问题；
• Output 若报告丢弃若干模型建议，表示这些条目的原文锚点、坐标、字段或重叠校验失败；同批其他独立有效项仍会显示；
• 把鼠标放到 TeXLeaf AI 波浪线范围内才能看到对应 Hover；
• AI 问题不进入 Problems 是当前 0.8.11 的预期行为；请以装饰线、专用 Hover 和活动栏“AI 写作问题”为准；
• 活动栏“AI 写作问题”只展示当前活动 .tex；可从状态栏或 TeXLeaf: 显示 AI 写作问题列表 打开；
• 修改正文后，旧句与新句并集只作为局部复检上下文；问题失效只看实际编辑与累计 pending 的精确范围。与局部范围不相交的同句问题在 exact original、strict UTF-16 remap 和 editable prose 都成立时继续保留；在问题右端点追加词尾会使该旧问题失效。句号/空行 split/merge、同一事务多处编辑与零宽边界都会覆盖关联上下文，保存等空 change 不清结果；
• 如果列表显示“若干个改动句子等待局部复检”，表示后续 API 请求尚未成功，其他问题没有被清空。每句成功立即合并；同批后句失败不会回滚已经成功的前句；
• TeXLeaf: 清除 AI 写作问题 会持久清除标记但不修改正文；
• “本次会话忽略”不会永久写入词典，重启扩展宿主后不再保留。

Hover 已显示，但按 Ctrl+. 没反应

如果 Windows 正在使用微软拼音的中文模式，Ctrl+. 会先被输入法用于切换中文/英文标点，可能根本不会送到 VS Code。这不表示 TeXLeaf 没有提供 Code Action，也不是 API Key、模型、余额或其他扩展造成的响应失败。

• 先按 Shift 把微软拼音切换为英文输入模式，再把光标放在波浪线范围内按 Ctrl+.；
• 或按 F1 / Ctrl+Shift+P 搜索并运行“快速修复...”；
• 也可以右键问题范围选择“快速修复...”、点击灯泡，或在 0.8.9 的专用 Hover 中点击“应用这条建议”。

Hover 链接并不会绕过安全检查：它只调用 TeXLeaf 白名单中的内部应用命令，模型文字不能生成可执行链接；后端仍重新验证当前文档版本、问题身份、范围、exact original 与 editable prose。真正过期的建议不会修改正文。0.8.9 没有新增专用快捷键，也不会改写用户的微软拼音或 VS Code 键位设置。

接受建议后仍显示同一问题

自 0.8.7 起，单条 Quick Fix 或确认后的“应用全部”只要写入成功，就会立即消费对应问题并更新装饰线、专用 Hover、活动栏列表和本机持久记录。比如原文 one take 已改成 one takes 后，不应继续看到仍建议 one takes 的旧条目；右端点追加的 s 也会使原 take 范围失效。

如果正文已经是 replacement、Hover 仍显示相同 replacement，通常表示旧版把已应用问题保留在内存或精确源码缓存中，而不是 AI 又给出了一条有效新建议。先确认扩展详情显示 0.8.11，并运行 Developer: Reload Window。当前版本恢复缓存时会重新执行单条校验：候选若只锚定 take，但范围与紧邻上下文已经组成 takes，会作为截短范围丢弃；成功应用也会立即更新缓存。仍由旧扩展宿主残留的标记可运行 TeXLeaf: 清除 AI 写作问题 清理，再重新检查最小句子。若 0.8.11 在全新检查后仍可复现，请报告应用入口（Hover、灯泡、树菜单或应用全部）、应用前后的最小匿名句子和 Output → TeXLeaf 中不含正文的错误子码。

连续应用时反复提示“文档已变化”

旧版会把问题的绝对 UTF-16 offset 写入操作 ID。接受靠前的一条建议后，后续仍然有效的问题虽然能安全平移到新位置，却全部得到新 ID；已经显示的问题树节点或灯泡动作继续携带旧 ID，于是被笼统误报成“文档已变化”。这不是 Key、余额、模型、Base URL 或原文校验失败。

0.8.8 为安全保留的问题维持稳定 lineage ID，同时继续更新当前 fingerprint、版本、范围和 offset。刷新前已经显示的节点仍会在当前正文上重新验证 exact original 后应用。真正过期的旧节点不会修改正文；它只会触发列表刷新和一条短状态栏提示，不再弹出信息通知，也不会播放音效。“应用全部”也会在确认后按稳定 ID 重新解析最新安全状态，等价 state 对象刷新不会误失败；正文版本已变、任一捕获问题已移除/失效/无法唯一解析，或者范围、原文或重叠校验失败时仍会整批停止。确认后才出现的其他问题不属于本批。

重启后问题没有恢复，或恢复到不同位置

0.8.8 只把已经通过安全校验的问题记录保存在当前 Profile/扩展宿主的私有 globalStorage。它不写当前工作区、不随 Settings Sync 同步，也不保存论文全文；另一台电脑、另一个 Profile、Stable/Insiders 或不同 Remote host 看不到同一份本机缓存是正常现象。

• 只有完整源文的 UTF-16 长度和 SHA-256 与快照完全一致时，TeXLeaf 才按原 offset 重新验证每条 original、可编辑正文和截短 replacement；即使 hash 精确，当前范围与紧邻上下文已经组成完整 replacement 的旧候选也会被过滤；
• 源文被离线/外部修改、hash/长度不匹配时不会跨源搜索相同短语，而是安全丢弃缓存并要求重新检查；即使全文一致，单条范围、原文或可编辑区失效也会丢弃该条；
• 清除问题、关闭 AI、切换 Provider/Base URL 或清除 Key 会写入空记录，重启后不会恢复已清除建议；
• 单文档超过 2048 条、单记录超过 2 MiB，或 Profile 缓存超过 256 个文档/32 MiB 时会按安全上限截断或清理旧记录；
• pending、检查中状态与“本次会话忽略”不会跨重启恢复。

不要手工复制或编辑缓存来绕过恢复校验。若怀疑文件损坏，先用 TeXLeaf: 清除 AI 写作问题；格式、UTF-8、字段、控制字符或 TeX replacement 无效的记录会被自动拒绝并清理。

改写被拒绝

改写要求连续纯正文。不要把 \cite{...}、公式、TeX 命令或外围大括号包含在选区中；缩小到命令之间的一句话再试。请求期间文档变化、返回内容引入反斜杠/美元号/百分号/花括号或未通过原文检查时，TeXLeaf 会保留原文。

行内补全不显示

• 确认 texleaf.aiWriting.inlineCompletions=true，并且 VS Code Inline Suggest 没有被全局禁用；
• 光标需要位于已有自然语言上下文的普通正文中；
• 数学、命令、citation 和受保护参数中不显示是预期行为；
• 普通 Suggest 已经选中候选时，TeXLeaf 不抢占；
• 等待 completionDelayMs，或运行 TeXLeaf: 触发 AI 行内补全；
• 关闭 inlineCompletions 后不再请求是预期行为。

API 费用比预期高

自动句子检查与自动行内补全都会增加请求次数。自动检查虽然不会每键联网，但每批可处理最多 8 个改动句子，同一文档版本最多自动请求 64 个不同句子；手动整篇检查每次最多 32 个正文段。DeepSeek 可使用默认 deepseek-v4-flash，OpenAI 可使用默认 gpt-5.6-luna；关闭不需要的自动子功能，提高防抖时间，降低长度上限，并优先按小选区手动检查。不使用时关闭总开关；完整费用控制见 AI 写作助手。

Math Preview 不显示

检查：

• 当前是已保存 .tex，language ID 为 LaTeX/TeX；
• texleaf.mathPreview.enabled=true；
• presentation 是否是预期的 cursor/hover/both；
• 光标是否在完整或当前可安全识别的公式中；
• 是否位于注释、verb/verbatim、lstlisting、minted；
• 公式是否超过 maxSourceLength；
• 运行 TeXLeaf: 刷新 Math Preview；
• 查看 Output 中 MathJax render、timeout、macro 或 asset 错误。

只有空框或公式模糊

当前 0.8.11 使用 Base64 data: URI 给 cursor decoration，避免 Windows MAX_PATH 造成生成了 SVG 却加载为空框。若仍为空：

• 确认不是旧 VSIX；
• 刷新预览并 Reload Window；
• 用默认深色/浅色主题比较；
• 查看开发者工具是否拒绝 data URI；
• 提供公式最小复现。

模糊/锯齿受 Chromium、系统 DPI、显示器、字体缩放和 window.zoomLevel 影响。尝试整数 zoom、默认主题和系统推荐缩放进行对照。TeXLeaf 公式本身是 SVG path，不建议用 Custom CSS 给所有 path 加 stroke。

持续输入时 cursor 预览每键消失

先确认扩展详情显示 0.8.11。cursor / both 现在保留 last-known-good 卡片，在防抖和渲染期间用同一个稳定 decoration 原位换帧；短暂无效 TeX 或渲染失败有 750 ms 宽限，新输入会取消旧失败计时，Hover SVG 也只在真正请求 Hover 时写盘。旧版仍然每次文档变化就立即清空时，请升级并 Reload Window。

这不是永久保留过时内容：离开公式、关闭总开关、运行 TeXLeaf: 关闭当前 Math Preview，或停止在无效状态超过宽限后仍会清理。若选择纯 hover，VS Code 原生 Hover 在编辑器输入时可能自行关闭，这是宿主生命周期；需要连续输入不闪烁时使用 cursor 或 both 中的 cursor 卡片。

预览遮挡、裁切或对齐

• 行内 auto 应位于活动源码行下方；起始行对齐 delimiter，后续行对齐首个非空白字符；
• 行间预览应对齐 opening delimiter；
• 上下无空白时，decoration 无法给正文预留真实高度，可能临时遮住相邻行；
• 超宽行间公式右端裁切是已知 API 边界，不应通过错误跳到第 0 列解决；
• 可降低 scale、切换 hover、添加空白行或显式选择 above/below；
• 对齐问题请同时提供 opening 行、锚点/光标行、Tab Size、字体、Zoom 和截图。

平台专项

Windows

• 确认安装目录、Profile 路径和 workspace 中的中文/空格没有被自定义脚本错误转义；
• Zotero 与 VS Code 应在同一桌面会话；
• 安全软件不要阻止回环；
• 旧空框问题优先确认版本，不要手工清整个用户数据目录。

macOS

• 运行时正式支持 macOS；快捷键使用 Cmd+Alt+L，其余 Tab/Enter/Shift+Enter/Escape 与 Windows/Linux 相同；
• 确认下载的 VSIX 未被浏览器自动解压；
• Zotero 必须是当前用户桌面会话中的本机应用；
• 若视觉定位或抗锯齿异常，报告 Retina/非 Retina、显示缩放、主题和 window.zoomLevel；
• 仓库中的固定视觉宿主/CDP 辅助脚本当前以 Windows CLI/窗口路径为主要自动化环境，不随 VSIX 发布；Release 前仍应在真实 macOS VS Code 上人工验收片段、引用、浅/深主题预览和快捷键。

Linux

• 检查 code CLI 是否在 PATH；
• Flatpak/Snap/AppImage 与系统 Zotero 可能有沙箱边界；
• Wayland/X11 和分数缩放会影响 Chromium 抗锯齿与 decoration 像素；
• 报告发行版、桌面环境、显示协议和缩放。

创建高质量 Issue

请提供：

• TeXLeaf、VS Code、操作系统版本；
• Local/WSL/SSH/Container/Codespaces 与扩展安装位置；
• Zotero 和 Better BibTeX 版本（文献问题）；
• 最小 .tex/.bib 片段，删除个人信息和未公开文献数据；
• 相关设置的用户/工作区/语言覆盖；
• 是否安装 LaTeX Workshop、Ultra Math Preview 或键位扩展；
• 从全新 Profile 是否可复现；
• Output → TeXLeaf 日志；
• UI 问题的深/浅主题截图、DPI/缩放/Zoom。

不要上传完整 Zotero 数据库、私人 .bib、访问凭据、系统环境变量或整个 VS Code 用户目录。

相关页面

• 配置参考
• 片段与模板
• Snippet 格式
• AI 写作助手
• 文献与 Zotero
• Math Preview
• 开发与发布
• 首页