jacobinwwey_obsidian-NotEMD/README_zh.md

![GitHub Release](https://img.shields.io/github/v/release/Jacobinwwey/obsidian-NotEMD?label=Version&link=https%3A%2F%2Fgithub.com%2Jacobinwwey%2Fobsidian-NotEMD%2Freleases%2Flatest) ![GitHub Downloads](https://img.shields.io/github/downloads/Jacobinwwey/obsidian-NotEMD/total?logo=Obsidian&label=Downloads&labelColor=%237C3AED&color=%235b5b5b&link=https%3A%2F%2Fgithub.com%2Jacobinwwey%2Fobsidian-NotEMD%2Freleases%2Flatest)	![GitHub Repo stars](https://img.shields.io/github/stars/Jacobinwwey/obsidian-NotEMD?style=social)

[![Discord](https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/qnGgsQ9W) ![QQ](https://img.shields.io/badge/QQ-1104515865-12B7F5)


# Notemd — Obsidian AI 知识库构建插件

> **Notemd**（Note + EMD — 增强型 Markdown 文档）将 LLM 驱动的阅读转化为持久知识：wiki 链接、概念笔记、研究摘要、翻译和图表，全部写回你的 Obsidian 库。

[English](./README.md) | [简体中文](./README_zh.md) | [Español](./README_es.md) | [Français](./README_fr.md) | [Deutsch](./README_de.md) | [Italiano](./README_it.md) | [Português](./README_pt.md) | [繁體中文](./README_zh_Hant.md) | [日本語](./README_ja.md) | [한국어](./README_ko.md) | [Русский](./README_ru.md) | [العربية](./README_ar.md) | [हिन्दी](./README_hi.md) | [বাংলা](./README_bn.md) | [Nederlands](./README_nl.md) | [Svenska](./README_sv.md) | [Suomi](./README_fi.md) | [Dansk](./README_da.md) | [Norsk](./README_no.md) | [Polski](./README_pl.md) | [Türkçe](./README_tr.md) | [עברית](./README_he.md) | [ไทย](./README_th.md) | [Ελληνικά](./README_el.md) | [Čeština](./README_cs.md) | [Magyar](./README_hu.md) | [Română](./README_ro.md) | [Українська](./README_uk.md) | [Tiếng Việt](./README_vi.md) | [Bahasa Indonesia](./README_id.md) | [Bahasa Melayu](./README_ms.md)

📚 更多语言文档：请查看 [语言中心](./docs/i18n/README_zh.md)  
📖 浏览仓库文档：请查看 [文档中心](./docs/README.zh-CN.md)  
❓ **新增：** [常见问题 (FAQ)](./docs/faq.zh-CN.md)

```
=============================================
  _   _       _   _ ___    __  __ ___
 | \ | | ___ | |_| |___|  |  \/  |___ \
 |  \| |/ _ \| __| |___|  | |\/| |   | |
 | |\  | (_) | |_| |___   | |  | |___| |
 |_| \_|\___/ \__|_|___|  | |  | |____/
=============================================
      AI驱动的多语言知识增强工具
=============================================
```

## 什么是 Notemd？

Notemd 是一个**开源 Obsidian 插件**，集成 30+ 种大型语言模型 (LLM)，将你的笔记转化为结构化、可搜索的知识库。

与基于聊天的 AI 工具不同（见解在会话后消失），Notemd 将结果**直接写入你的库**，形式包括：
- **[[Wiki 链接]]** 连接关键概念
- **概念笔记** 记录术语和想法
- **研究摘要** 附带来源引用
- **翻译** 支持多语言工作流
- **Mermaid 图表** 和可视化图表

**结果：** 你的阅读和研究积累成持久的、不断演化的知识图谱，永远伴随你。

如果您喜欢使用 Notemd，请考虑 [⭐ 给 GitHub 加星](https://github.com/Jacobinwwey/obsidian-NotEMD) 或 [☕️ 请喝杯咖啡](https://ko-fi.com/jacobinwwey)。

**版本:** 1.9.4

![GitHub Release](https://img.shields.io/github/v/release/Jacobinwwey/obsidian-NotEMD?label=Version&link=https%3A%2F%2Fgithub.com%2Jacobinwwey%2Fobsidian-NotEMD%2Freleases%2Flatest) ![GitHub Downloads](https://img.shields.io/github/downloads/Jacobinwwey/obsidian-NotEMD/total?logo=Obsidian&label=Downloads&labelColor=%237C3AED&color=%235b5b5b&link=https%3A%2F%2Fgithub.com%2Jacobinwwey%2Fobsidian-NotEMD%2Freleases%2Flatest)

<img width="1853" height="1080" alt="show" src="https://github.com/user-attachments/assets/b9f9292b-a9d8-48a3-9acf-1b6f00413966" />
<img width="1853" height="1080" alt="multi-langu" src="https://github.com/user-attachments/assets/d9a0a4fb-1c00-425a-ac1d-0134a013a381" />
<img width="1657" height="1000" alt="NEW FEATURE" src="https://github.com/user-attachments/assets/1d97ca0d-2ea6-41a4-accc-be3be9590088" />

## 目录
- [快速入门](#快速入门)
- [语言支持](#语言支持)
- [功能特性](#功能特性)
- [安装](#安装)
- [配置](#配置)
- [使用指南](#使用指南)
- [支持的LLM提供商](#支持的llm提供商)
- [网络使用与数据处理](#网络使用与数据处理)
- [故障排除](#故障排除)
- [贡献](#贡献)
- [维护者文档](#维护者文档)
- [许可证](#许可证)

## 快速入门

1.  **安装与启用**：从 Obsidian 市场获取插件。
2.  **配置 LLM**：进入 `设置 -> Notemd`，选择您的 LLM 提供商（如 OpenAI 或本地提供商如 Ollama），并输入 API 密钥/URL。
3.  **打开侧边栏**：点击左侧工具栏中的 Notemd 魔法棒图标以打开侧边栏。
4.  **处理笔记**：打开任意笔记，在侧边栏中点击 **“处理文件 (添加链接)”**，即可自动为关键概念添加 `[[wiki-links]]` 链接。
5.  **运行快捷工作流**：使用默认的 **“One-Click Extract”** 按钮，可一键串联处理、批量生成与 Mermaid 修复。

完成！探索更多设置以解锁网页搜索、翻译和内容生成等功能。

## 语言支持

### 语言行为契约

| 关注点 | 控制范围 | 默认值 | 说明 |
|---|---|---|---|
| `界面语言` | 仅影响插件界面文案（设置、侧边栏、提示、弹窗） | `auto` | 跟随 Obsidian 语言；当前 UI 语言包为 `en`、`ar`、`de`、`es`、`fa`、`fr`、`id`、`it`、`ja`、`ko`、`nl`、`pl`、`pt`、`pt-BR`、`ru`、`th`、`tr`、`uk`、`vi`、`zh-CN`、`zh-TW`。 |
| `任务输出语言` | 影响 LLM 任务输出（链接、摘要、生成、提取、翻译目标） | `en` | 可使用全局语言，或开启“按任务设置语言”。 |
| `禁用自动翻译` | 非翻译任务保持原文语境 | `false` | 显式“翻译”任务仍按目标语言执行。 |
| Locale 回退 | UI 文案缺失时的回退策略 | 当前 locale -> `en` | 属于实现层安全网；已支持 locale 的可见界面已由回归测试覆盖，正常使用中不应再静默回落到英文。 |

- 维护源文档为 English + 简体中文，已发布的 README 译文已在上方页眉列出。
- 应用内 UI locale 覆盖目前与代码中的显式语言目录一致：`en`、`ar`、`de`、`es`、`fa`、`fr`、`id`、`it`、`ja`、`ko`、`nl`、`pl`、`pt`、`pt-BR`、`ru`、`th`、`tr`、`uk`、`vi`、`zh-CN`、`zh-TW`。
- English 回退仍保留为实现层安全网，但已支持 locale 的可见界面已由回归测试覆盖，正常使用中不应再静默回落到英文。
- 更多详情及贡献指南请参阅 [语言中心](./docs/i18n/README_zh.md)。

## 功能特性

### AI驱动的文档处理
- **多 LLM 支持**: 连接到各种云和本地 LLM 提供商（参见 [支持的LLM提供商](#支持的llm提供商)）。
- **智能分块**: 根据字数自动将大型文档分割成易于管理的小块进行处理。
- **内容保留**: 在添加结构和链接的同时，旨在保持原始内容格式。
- **进度跟踪**: 通过 Notemd 侧边栏或进度模式进行实时更新。
- **可取消操作**: 可以通过侧边栏的专用取消按钮取消任何处理任务（单个或批量）。命令面板操作使用模式窗口，也可以取消。
- **多模型配置**: 为不同任务（添加链接、研究、生成标题）使用不同的 LLM 提供商*和*特定模型，或为所有任务使用单一提供商。
- **稳定的 API 调用（重试逻辑）**: 可选择为失败的 LLM API 调用启用自动重试，并可配置重试间隔和尝试次数限制。
- **更稳健的 Provider 连接测试**: 当 Provider 的首次连接测试遇到瞬时断连时，Notemd 现在会先回退到稳定重试序列再判定失败，覆盖 OpenAI-compatible、Anthropic、Google、Azure OpenAI 与 Ollama 五类传输链路。
- **运行时环境传输回退**: 当长耗时 Provider 请求被 `requestUrl` 以 `ERR_CONNECTION_CLOSED` 等瞬时网络错误中断时，Notemd 现在会先在同一次调用内切换到与运行环境匹配的回退传输：桌面端使用 Node `http/https`，非桌面环境使用浏览器 `fetch`；只有在该回退也失败时，才进入配置好的稳定重试序列，从而降低慢速网关或反向代理下的误报失败。
- **OpenAI-compatible 稳定长请求链路加固**: 在稳定模式下，OpenAI-compatible 每次调用现在会按 `直连流式 -> 直连非流式 -> requestUrl` 的顺序依次尝试（必要时 `requestUrl` 仍可升级为流式解析），再决定是否进入下一次重试。这可降低“Provider 实际已返回非流式结果，但流式链路不稳定”导致的误失败。
- **全 LLM API 的协议感知流式回退**: 长耗时回退请求现在不再只覆盖 OpenAI-compatible Provider，而是扩展到所有内置 LLM 路径。Notemd 现在会在桌面 `http/https` 与非桌面 `fetch` 回退阶段，分别处理 OpenAI/Azure 风格 SSE、Anthropic Messages SSE、Google Gemini SSE，以及 Ollama 的 NDJSON 流式输出，其余直连的 OpenAI 风格 Provider 入口也会复用同一套共享回退路径。
- **中国区 Provider 预设增强**: 内置补充了 `Qwen`、`Qwen Code`、`Doubao`、`Moonshot`、`Xiaomi MiMo`、`GLM`、`Z AI`、`MiniMax`、`Huawei Cloud MaaS`、`Baidu Qianfan`、`SiliconFlow` 等中国区常用云端模型服务商预设。
- **可靠的批处理**: 改进了并发处理逻辑，通过**交错的API调用**来防止速率限制错误，确保在大型批处理作业中性能稳定。新的实现确保任务在不同时间间隔启动，而不是同时启动。
- **准确的进度报告**: 修复了进度条可能卡住的错误，确保用户界面始终反映操作的真实状态。
- **健壮的并行批处理**: 解决了并行批处理操作过早停止的问题，确保所有文件都能可靠高效地处理。
- **进度条准确性**: 修复了“创建维基链接并生成笔记”命令进度条卡在95%的错误，确保现在能正确显示100%完成。
- **增强的API调试**: “API错误调试模式”现在不仅可以捕获来自 LLM 提供商和搜索服务（Tavily/DuckDuckGo）的完整响应体，还会记录按尝试维度展开的传输时间线，包括脱敏后的请求 URL、耗时、响应头、部分响应体、已解析的部分流式内容与堆栈信息，从而更适合定位 OpenAI-compatible、Anthropic、Google、Azure OpenAI、Ollama 等链路上的 429/500 错误、网关断连和其他 API 故障。
- **开发者模式面板**: 设置中新增独立 Developer 诊断面板，默认隐藏，只有开启“Developer mode”后才显示。该面板支持选择诊断调用方式，并可按指定方式执行多轮稳定性测试。
- **开发者开关控制的放开输入文件限制**: 开发者设置中新增 `放开输入文件限制` 开关，用于只对保留原文件的输入型任务放开当前平面 `.md` / `.txt` 限制。开启后，`Translate current file`、`Batch translate folder`、`Extract concepts（当前/文件夹）`、`Summarise as Mermaid diagram`、`Generate diagram`、`Check duplicates in current file` 可额外读取更多文本类文件以及通过 Obsidian PDF 运行时提取文本的 PDF；涉及原文改写、Markdown 结构依赖或逐字对照的流程仍保持限制。
- **重构后的侧边栏**: 内置操作按用途分组展示，并提供更清晰的标签、实时状态、可取消进度和可复制日志，显著减少按钮堆叠带来的混乱。即使所有分组都展开，底部的进度与日志区域也会保持可见，Ready 状态下的待机进度轨道也更容易辨认。
- **侧边栏交互与可读性打磨**: 侧边栏按钮补齐了更清晰的悬停/按下/焦点反馈；`One-Click Extract`、`Batch generate from titles` 等彩色 CTA 按钮也强化了文字对比度，在不同主题下可读性更好。
- **单文件 CTA 映射规则**: 彩色 CTA 现在仅用于“单文件处理”动作；批量/文件夹级动作以及包含批量步骤的工作流会使用非 CTA 样式，降低动作范围误判风险。
- **自定义一键工作流**: 可将内置侧边栏操作组装成可复用的自定义按钮，支持用户命名与动作编排，默认内置 `One-Click Extract` 工作流。
- **欢迎弹窗更新摘要**: 首次安装时，欢迎弹窗现会在可滚动区域中展示最近两个版本的更新摘要，便于用户在配置 Provider 前快速了解新增能力。
- **设置重置**: 设置页现提供“完全重置”和“部分重置（保留 Provider 配置）”两种收口按钮，便于快速恢复默认配置。
- **文件夹任务筛选档案**: 文件夹任务现支持可复用的命名筛选档案，覆盖 regex/glob、`relativePath` / `basename` 匹配目标以及子文件夹范围控制。

### 知识图谱增强
- **自动维基链接**: 根据 LLM 输出，识别您处理过的笔记中的核心概念并添加 `[[维基链接]]`。
- **概念笔记创建（可选和可定制）**: 在指定的 vault 文件夹中自动为发现的概念创建新笔记。
- **可定制的输出路径**: 在您的 vault 中为保存处理过的文件和新创建的概念笔记配置单独的相对路径。
- **可定制的输出文件名（添加链接）**: 在处理文件以添加链接时，可选择**覆盖原始文件**或使用自定义后缀/替换字符串，而不是默认的 `_processed.md`。
- **链接完整性维护**: 在 vault 内重命名或删除笔记时，基本处理更新链接的功能。
- **纯概念提取**: 提取概念并创建相应的概念笔记，而不修改原始文档。这对于从现有文档中填充知识库而不改变它们是理想的。此功能具有用于创建最简概念笔记和添加反向链接的可配置选项。
- **概念生成前置守卫**: 当概念笔记路径未按要求启用或配置时，相关流程会先弹窗提示，并可直接跳转到对应设置位置。
- **概念同义词抑制**: 可选地让模型在处理文件/文件夹与提取概念时，尽量避免抽取同义词、语义近似核心概念或近重复关键词。
- **本地知识检索**: `从标题生成`、`从标题批量生成`、`研究与总结`、`生成图形` 现在可选接入本地知识库检索，支持配置 Vault 相对文件/文件夹路径以及按任务覆盖的知识库来源；上下文完全在插件内本地构建，不依赖云检索服务或常驻外部进程。
- **章节拆分 + TOC 提取**: 可按标题层级将笔记拆成章节文件，并在源文件旁生成带 front-matter metadata 的可链接 TOC；重复执行时还会清理陈旧产物。

### 翻译

- **AI 驱动的翻译**：
    - 使用配置的 LLM 翻译笔记内容。
    - **大文件支持**：在发送给 LLM 之前，会根据 `分块字数` 设置将大文件自动拆分为更小的块。翻译后的块随后会无缝地合并回单个文档中。
    - 支持多种语言之间的翻译。
    - 可在设置或 UI 中自定义目标语言。
    - 自动在原始文本右侧打开翻译后的文本，便于阅读。
- **批量翻译**:
    - 一键翻译所选文件夹中的所有文件。
    - 当“启用批处理并行化”开启时，支持并行处理。
    - 如果已配置，则使用自定义提示进行翻译。
	- 在文件浏览器的上下文菜单中添加“批量翻译此文件夹”选项。
- **禁用自动翻译**: 启用此选项后，非翻译任务将不再强制输出为特定语言，从而保留原始语言上下文。明确的“翻译”任务仍将按配置执行翻译。

### 网络研究与内容生成
- **网页研究与摘要**:
    - 支持Tavily（需API Key）与DuckDuckGo（实验性）两种网络搜索服务。
    - **改进的搜索稳定性**: DuckDuckGo 搜索现在具有增强的解析逻辑（DOMParser 与 Regex 回退），以处理布局变化并确保结果的可靠性。
    - 自动用LLM总结搜索结果，并附加到当前笔记。
    - 可以在设置中自定义摘要的输出语言。
    - 可配置用于研究的最大内容长度。
- **根据标题生成内容**:
    - 利用笔记标题通过LLM生成内容并替换原有文本。
    - 可选在生成前自动执行网页研究，丰富生成上下文。
- **批量根据标题生成内容**:
    - 一键批量处理选定文件夹下所有笔记，自动跳过已处理文件。
    - 可配置“完成”子文件夹名称，避免重复处理。
- **Mermaid 自动修复耦合**:
    - 当启用 Mermaid 自动修复后，处理、按标题生成、批量按标题生成、研究与摘要、总结为 Mermaid、翻译等 Mermaid 相关流程都会在输出后自动执行修复，减少图表语法残留与人工返工。

### 实用功能
- **总结为Mermaid图表**:
    - 此功能允许您将笔记内容总结为Mermaid图表。
    - 可以在设置中自定义Mermaid图表的输出语言。
    - **Mermaid 输出文件夹**: 配置生成Mermaid图表文件的保存文件夹。如果留空，图表将保存在与原始笔记相同的文件夹中。
    - **翻译总结为Mermaid输出**: 可选地将生成的Mermaid图表内容翻译成配置的目标语言。

<img width="596" height="239" alt="SUMM" src="https://github.com/user-attachments/assets/803d444f-e477-428a-9ce6-4aac8075062a" />

- **实验性图表流水线**:
    - 规范优先的图表路径可以把笔记内容路由到 Mermaid、Obsidian JSON Canvas、Vega-Lite、HTML、可编辑 HTML/SVG、Draw.io、Drawnix 或受约束 circuitikz，而不是把所有场景都压回 Mermaid 文本生成。
    - `mindmap`、`flowchart`、`sequenceDiagram`、`classDiagram`、`erDiagram` 与 `stateDiagram-v2` 仍由 Mermaid adapter 覆盖；`dataChart` 使用受控 Vega-Lite 模板；`circuit` 使用 `circuitikz` render target。
    - 预览弹窗可把可渲染输出或 SVG companion 导出为 `.svg`、`.png` 与 `.pdf`；PNG/PDF 默认 300 PPI，超过 600 PPI 的配置会被夹到 600。
    - Draw.io、Drawnix 与 Circuitikz 都保持 artifact 边界：插件不捆绑 diagrams.net、Drawnix、Plait、LaTeX 或 TikZJax runtime，而是写出原生源文件和 Obsidian 可查看的 SVG companion。
    - 电路图必须使用 `intent: "circuit"` 与已验证 `CircuitSpec`。`CircuitikzRenderer` 会写出确定性 `.tex`，并附加用于 Obsidian 预览和 SVG/PNG/PDF 导出的 SVG companion；该 companion 不是 LaTeX/TikZJax 编译结果。

| 目标 | 生成 artifact | 内联预览 | 导出 SVG | 导出 PNG | 导出 PDF | 保存源文件 | 备注 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Mermaid | `_summ.md` | 是 | 是 | 是 | 是 | 是 | Mermaid-only 流程仍可使用 Mermaid auto-fix。 |
| JSON Canvas | `_diagram.canvas` | 是 | 是 | 是 | 是 | 是 | 预览/导出使用主题感知 Canvas 配色。 |
| Vega-Lite | `_diagram.json` | 是 | 是 | 是 | 是 | 是 | 预览/导出使用主题感知 Vega-Lite 配置补丁。 |
| 可编辑 HTML/SVG | `_diagram.html` | 是 | 是 | 是 | 是 | 是 | SVG 从语义 figure model 生成。 |
| Draw.io | `_diagram.drawio` + SVG/MD companion | SVG companion | 是 | 是 | 是 | 是 | 不捆绑 diagrams.net runtime。 |
| Drawnix | `_diagram.drawnix` + SVG/MD companion | SVG companion | 是 | 是 | 是 | 是 | 不捆绑 Drawnix 或 Plait runtime。 |
| Circuitikz | `_diagram.tex` + SVG/MD companion | SVG companion | 是 | 是 | 是 | 是 | 需要 `intent: "circuit"` 与已验证 `CircuitSpec`；不在 runtime 编译 LaTeX。 |
| HTML | `_diagram.html` | 是（iframe fallback） | 否 | 否 | 否 | 是 | 通用 HTML fallback 暂不承诺栅格/矢量导出。 |

- **简单公式格式修正**:
    - 快速将单行 `$` 分隔的数学公式转换为标准的 `$$` 块。
    - **单文件**: 通过侧边栏按钮或命令面板处理当前文件。
    - **批量修复**: 通过侧边栏按钮或命令面板处理所选文件夹中的所有文件。

- **检查当前文件中的重复项**: 此命令有助于识别活动文件中的潜在重复术语。
- **重复检测**: 检查当前处理内容中的重复词（结果输出到控制台）。
- **检查并删除重复概念笔记**: 综合文件名（精确/复数/规范化/包含关系）检测概念笔记文件夹内外潜在重复项，支持自定义检测范围，操作前会详细列出并需手动确认。
- **批量Mermaid修复**: 对选定文件夹内所有Markdown文件应用Mermaid和LaTeX语法校正。
    - **可作为工作流步骤**: 除了单独执行外，也可以作为自定义一键工作流中的一步进行组合。
    - **错误报告**: 生成 `mermaid_error_{foldername}.md` 报告，列出处理后仍包含潜在Mermaid错误的文件。
    - **移动错误文件**: 可选地将检测到错误的文件移动到指定文件夹以供手动审查。
    - **智能检测**: 在尝试修复之前，使用 `mermaid.parse` 智能检查文件是否存在语法错误，节省处理时间并避免不必要的编辑。
    - **安全处理**: 确保语法修复仅应用于 Mermaid 代码块，防止意外修改 Markdown 表格或其他内容。包含针对表格语法（例如 `| :--- |`）的稳健保护措施，防止被深度调试功能误修。
    - **深度调试模式**: 如果初始修复后错误仍然存在，将触发高级深度调试模式。此模式处理复杂的边缘情况，包括：
        - **注释集成**: 自动将尾随注释（以 `%` 开头）合并到连接线标签中（例如，`A -- Label --> B; % Comment` 变为 `A -- "Label(Comment)" --> B;`）。
        - **畸形箭头**: 修复被引号吸收的箭头（例如 `A -- "Label -->" B` 修正为 `A -- "Label" --> B`）。
        - **行内子图**: 将行内子图标签转换为连接线标签。
        - **反向箭头修复**: 将非标准的 `X <-- Y` 箭头修正为 `Y --> X`。
        - **方向关键字修复**: 确保子图内的 `direction` 关键字为小写（例如 `Direction TB` -> `direction TB`）。
        - **注释转换**: 将 `//` 注释转换为连接线标签（例如 `A --> B; // 注释` -> `A -- "注释" --> B;`）。
        - **重复标签修复**: 简化重复的括号标签（例如 `Node["标签"]["标签"]` -> `Node["标签"]`）。
        - **无效箭头修复**: 将无效的箭头语法 `--|>` 转换为标准的 `-->`。
        - **稳健的标签与注释处理**: 改进了对包含特殊字符（如 `/`）的标签的处理，并更好地支持自定义注释语法（`note for ...`），确保彻底清除尾随括号等残留物。
        - **高级修复模式**: 包含针对包含空格、特殊字符或嵌套括号的未加引号节点标签的稳健修复（例如，将 `Node[标签 [文本]]` 转换为 `Node["标签 [文本]"]`）。
        - **注释转换**: 自动将 `note right/left of` 以及独立的 `note :` 注释转换为标准的 Mermaid 节点定义和连接（例如，将 `note right of A: text` 转换为 `NoteA["Note: text"]` 并连接到 `A`），防止语法错误并改善布局。
        - **扩展注释支持**: 自动将 `note for Node "Content"` 和 `note of Node "Content"` 转换为标准的链接注释节点（例如 `NoteNode[" Content"]` 连接到 `Node`），确保与用户扩展语法的兼容性。
        - **增强的注释修正**: 自动使用顺序编号（如 `Note1`, `Note2`）重命名注释，以防止存在多个注释时出现别名问题。
        - **平行四边形/形状修复**: 修正畸形的节点形状定义，如将 `[/["标签["/]` 转换为标准的 `["标签"]`，确保与生成内容的兼容性。
        - **标准化管道标签**: 自动修复和标准化包含管道符的连接线标签，确保它们被正确引用（例如，将 `-->|文本|` 转换为 `-->|"文本"|`）。
        - **错位管道修复**: 修正出现在箭头之前的错位连接线标签（例如 `>|"标签"| A --> B` 修正为 `A -->|"标签"| B`）。
        - **合并双重标签**: 检测并合并单条边上的复杂双重标签（例如，`A -- 标签1 -- 标签2 --> B` 或 `A -- 标签1 -- 标签2 --- B`），将其转换为带有换行的单个清晰标签（`A -- "标签1<br>标签2" --> B`）。
        - **未加引号的标签修复**: 自动为包含潜在问题字符（如引号、等号、数学运算符）但缺少外引号的节点标签添加引号（例如，将 `Plot[Plot "A"]` 修正为 `Plot["Plot "A""]`），防止渲染错误。
        - **连接标签修复**: 稳健地修复 ID 与标签连接的节点定义（例如，`SubdivideSubdivide...` 变为 `Subdivide["Subdivide..."]`），即使在前面有管道标签或重复不完全的情况下，也能通过验证已知节点 ID 进行修复。
        -   **提取特定原始内容**:    - 在设置中定义问题列表。
    - 从活动笔记中逐字提取回答这些问题的文本段落。
    - **合并查询模式**: 可选择在单个 API 调用中处理所有问题以提高效率。
    - **翻译**: 可选在输出中包含提取文本的翻译。
    - **自定义输出**: 可配置提取文本文件的保存路径和文件名后缀。
- **LLM连接测试**: 一键检测所有配置LLM服务商的API连接状态。

## 安装

<img width="819" height="733" alt="Install" src="https://github.com/user-attachments/assets/f1733532-68fd-4c47-86b4-6fcc185e3f66" />

### 通过Obsidian市场（推荐）
1. 打开Obsidian **设置** → **社区插件**。
2. 确认“受限模式”已关闭。
3. 点击“浏览”社区插件，搜索“Notemd”。
4. 点击“安装”。
5. 安装后点击“启用”。

### 手动安装
1. 从 [GitHub发布页](https://github.com/Jacobinwwey/obsidian-NotEMD/releases) 下载最新发布资产。每个 Release 也会附带 `README.md` 作为随包文档，但手动安装实际只需要 `main.js`、`styles.css`、`manifest.json`。
2. 进入 `<您的保险库>/.obsidian/plugins/` 目录。
3. 新建 `notemd` 文件夹，将 `main.js`、`styles.css`、`manifest.json` 拷贝至此。
4. 重启Obsidian。
5. 在“社区插件”中启用Notemd插件。

## 配置

<!-- notemd-settings-discovery-guide -->
### 查找并复用设置

Notemd 的设置较多，是因为模型提供商、笔记工作流、图表、批处理、幻灯片和开发者诊断分别需要不同控制项。设置页现在提供模糊搜索、大类导览和单项收藏。收藏按当前 Vault 保存，重启 Obsidian 后仍然可用。

较新的重要设置包括：

- **图形历史保留上限**：限制 Vault 历史索引数量；清理索引不会删除已生成文件。
- **图形预览导出 PPI**：控制 PNG 和 PDF 清晰度；SVG 始终保持矢量格式。
- **首选图表类型 / 生成格式**：把图表语义与 Mermaid、Draw.io、Drawnix、CircuitikZ 等可编辑源格式分开。
- **CircuitikZ 原生编译环境（可选）**：检查已有 `tectonic` 或 `pdflatex`，也可在用户明确确认后安装固定版本的托管 Tectonic。未安装 LaTeX 时，SVG、PNG 和预览 PDF 导出仍然可用。
- **高级批处理文件选择**：启用可保存的文件夹/文件选择配置和规则预览。
- **自动创建缺失的批处理目标文件夹**：用户首次授权后可启用；已经存在且非空的文件夹仍会在每次批处理开始前确认一次。
- **开发者模式**：显示用于故障排查的 provider 诊断与高级文件选择工具。

### 图形历史

完成的图形预览会写入 Vault 级索引，并默认按完成时间倒序排列。预览以图形画布为主：单一**导出**菜单提供 SVG、PNG 和 PDF，点击**历史**会在不关闭预览的情况下打开右侧可搜索抽屉。即使当前没有活动笔记，也能从命令面板（`Notemd: 打开图形历史`）或侧边栏直达同一历史视图。可按标题、笔记、图表类型、源格式或导出格式搜索，并以每页 20 条浏览结果。历史只保存轻量元数据和产物路径，不重复保存 SVG、PNG、PDF 或源文件正文。删除历史记录不会删除生成文件。

### 可选的 CircuitikZ 原生编译

Notemd 不会把完整 TeX 发行版塞进插件包。桌面端可从图形设置或命令面板打开 **CircuitikZ 原生编译环境**，复用系统 `tectonic` / `pdflatex`、选择自定义可执行文件，或显式安装/修复固定版本的托管 Tectonic。环境面板会显示就绪状态、下载进度、安装目录、有限长度日志和删除入口。移动端以及选择不安装的用户仍可使用零依赖预览，并导出 SVG、PNG 和预览 PDF。

### 安全的批处理文件夹处理

从标题批量生成开始前，Notemd 会对所选文件夹统一检查一次：

- 文件夹不存在时可在确认后创建，并可记住“以后自动创建缺失的批处理目标文件夹”。
- 已存在的空文件夹直接使用。
- 已存在的非空文件夹只在整次批处理开始前确认一次，不会逐个生成文件询问。
- 路径实际对应文件时，会给出可操作的错误提示。
- 无交互 CLI 调用返回可恢复状态，不会静默创建或授权文件夹。

进入设置：**设置** → **社区插件** → **Notemd**（齿轮图标）。

### LLM 提供商配置

1. **活动提供商**: 从下拉菜单中选择您想要使用的 LLM 提供商。

2. 提供商设置

   : 配置所选提供商的具体设置：

   - **API 密钥**: 大多数云提供商（例如 OpenAI、Anthropic、DeepSeek、Qwen、Qwen Code、Doubao、Moonshot、Xiaomi MiMo、GLM、Z AI、MiniMax、Huawei Cloud MaaS、Baidu Qianfan、SiliconFlow、Google、Mistral、Azure OpenAI、OpenRouter、xAI、Groq、Together、AIHubMix、GitHub Models、PPIO、Fireworks、Nebius、Cerebras、Hugging Face、Vercel AI Gateway、Requesty）需要。Ollama 不需要。LMStudio、LiteLLM、`New API`、`OVMS` 和通用的 `OpenAI Compatible` 预设在某些允许匿名或占位密钥的端点上可留空。
   - **基础 URL / 端点**: 服务的 API 端点。提供了默认值，但您可能需要为本地模型（LMStudio、Ollama）、网关（OpenRouter、Requesty、OpenAI Compatible）或特定 Azure 部署修改此项。**Azure OpenAI 必填。**
   - **模型**: 要使用的具体模型名称/ID（例如 `gpt-4o`, `claude-3-5-sonnet-20240620`, `google/gemini-flash-1.5`, `grok-4`, `moonshotai/kimi-k2-instruct-0905`, `accounts/fireworks/models/kimi-k2p5`, `anthropic/claude-3-7-sonnet-latest`）。请确保该模型在您的端点/提供商处可用。
   - **API 版本（仅 Azure）**: Azure OpenAI 部署需要（例如 `2024-02-15-preview`）。
   - **高级设置**: `Temperature`、`Top-p`、reasoning hint、DeepSeek thinking mode、provider 级 output-token override 等次级调优项现在统一收入 **显示高级设置**。如果某个 provider 已经保存了 advanced override，该区域会默认展开，避免现有行为被静默藏起来。
   - **获取模型列表**: 已支持的 provider 可以直接向端点查询可用 model ID，但不会替代手动 `Model` 输入。当前有界支持覆盖一批已验证的 OpenAI-compatible `/models` 预设：包括 DeepSeek / OpenAI / Mistral，`Qwen`、`Qwen Code`、`Doubao`、`Moonshot`、`Xiaomi MiMo`、`GLM`、`Z AI`、`MiniMax`、`Baidu Qianfan`、`SiliconFlow` 等中国区托管端点，`Groq`、`Fireworks`、`Nebius`、`Cerebras`、`Hugging Face` 等高速推理端点，`OpenRouter`、`Requesty`、`LiteLLM`、`AIHubMix`、`GitHub Models`、`PPIO`、`New API` 等网关，以及本地 `LMStudio`、`OVMS` 服务。同时也覆盖 Together 专用 `/models` 响应形态、Anthropic `GET /models`、xAI 专用 `/v1/language-models` 并有界回退到 `/v1/models`、Huawei Cloud MaaS 专用 `v2/models` 模型注册表接口、GitHub Models 的有界 `catalog/models` + `/v1/models` 双源合并、PPIO 的有界 chat + embedding + reranker 三路合并、OVMS 优先走本地 `/v3/models` 并在必要时有界回退到 legacy `/v1/config`、Vercel AI Gateway 对官方 `/v1/models` 与 `v3/ai/config` 的有界双源合并、Ollama tags 与 Google Gemini model listing。`OpenRouter` 现在会有界地合并 chat 与 embedding catalog，而 Anthropic 与 Google 在 provider 返回分页 catalog 时，也会按有界多页遍历合并模型结果。更广义的 OpenAI-compatible 发现链路现在也会在模型目录返回 `next_url`、`links.next`、`nextPageToken`、`next_cursor` 等 continuation 信号时执行同样的有界翻页，因此较大的 gateway catalog 不会静默截断到第一页，而且后续页面失败时也不会丢掉前面已经成功获取的有效模型。对于会返回更宽模型目录的 provider，当前发现结果会刻意优先保留适合生成任务的模型，避免 embedding、reranker、speech、classifier 等条目把模型选择器挤满；共享 parser 现在也能利用更宽的代理/catalog 元数据，包括 `list`/`items`、`rows`/`records`、`value`/`values`、object-shaped catalogs、嵌套 `data`/`result` 集合、托管 registry 中的 `types` 分类、`publisherModels` 一类注册表、`data.provider_models` / `result.data.publisherModels` 这类包裹式目录、`registry` / `registries` / `services` 这类包裹式目录、LiteLLM 风格的 `litellm_params` + `model_info` 元数据、endpoint-type metadata、瞬时显示标签、max-output-token 提示，以及 capability/modality/status 信号，还能识别 `uid`、`identifier`、`modelId`、`provider_model_id` 这类更宽的主标识字段，并把 `models/<id>`、`publishers/<owner>/models/<id>` 这类资源名归一化回可直接使用的 model id，尽量过滤掉不可用或非文本输出模型，同时避免把所有 provider alias 都膨胀成独立选项。`Azure OpenAI` 仍保持 manual-first。通用 `OpenAI Compatible` 预设现在会在已知 host（如 OpenRouter、Requesty、Together、xAI、Huawei Cloud MaaS、Vercel AI Gateway、`AIHubMix`、`GitHub Models`、`PPIO`、本地 LiteLLM 风格代理，以及 OVMS 风格的本地 `/v3` 端点）上自动升级到对应的有界发现 family；如果不是这些已知 host，则仍会在自定义端点暴露标准 `/models` 时尝试通用远端发现。共享的 OpenAI-compatible URL 归一化现在也容忍用户把基础 URL 直接填到 `/responses`、`/chat/completions` 或 `/models`；即使用户粘贴的地址还带 query string 或 hash fragment，也不会破坏获取模型列表或实际调用。当这个通用预设指向 OpenAI、DashScope/Qwen、Xiaomi MiMo、Fireworks、Hugging Face 这类已知官方 host 时，model-aware token guidance 现在也能对 bare model ID 复用上游 provider 的已知 output-token cap，而不再强依赖 provider-prefixed model name。获取到的列表只是瞬时建议，持久化真值仍然是用户保存的 `Model` 字符串。

3. **测试连接**: 使用活动提供商的“测试连接”按钮来验证您的设置。OpenAI-compatible 提供商现在会按 provider 特性自动选择测试策略：`Qwen`、`Qwen Code`、`Doubao`、`Moonshot`、`Xiaomi MiMo`、`GLM`、`Z AI`、`MiniMax`、`Huawei Cloud MaaS`、`Baidu Qianfan`、`SiliconFlow`、`Groq`、`Together`、`Fireworks`、`LMStudio` 与 `OpenAI Compatible` 会直接探测 `chat/completions`，而具备稳定 `/models` 端点的服务仍会优先走模型列表探测。如果首次探测遇到 `ERR_CONNECTION_CLOSED` 这类瞬时网络断连，Notemd 会自动切入稳定重试序列，而不是立刻报错。

4. **管理提供商配置**: 使用“导出提供商”和“导入提供商”按钮将您的 LLM 提供商设置保存到插件配置目录中的 `notemd-providers.json` 文件或从中加载。这便于备份和共享。

5. **预设覆盖范围**: 除了原有提供商外，Notemd 现在还内置了 `Qwen`、`Qwen Code`、`Doubao`、`Moonshot`、`Xiaomi MiMo`、`GLM`、`Z AI`、`MiniMax`、`Huawei Cloud MaaS`、`Baidu Qianfan`、`SiliconFlow`、`xAI`、`Groq`、`Together`、`AIHubMix`、`GitHub Models`、`PPIO`、`New API`、`OVMS`、`Fireworks`、`LiteLLM`、`Nebius`、`Cerebras`、`Hugging Face`、`Vercel AI Gateway`、`Requesty` 以及通用的 `OpenAI Compatible` 预设，可用于自定义代理。

<img width="804" height="506" alt="LLM" src="https://github.com/user-attachments/assets/8caf42e3-43ad-456d-8b96-b63e7914e45f" />

### 多模型配置

- 为任务使用不同的提供商

  :

  - **禁用 (默认)**: 对所有任务使用上面选择的单个“活动提供商”。
  - **启用**: 允许您为每个任务（“添加链接”、“研究与摘要”、“从标题生成”、“提取概念”）选择特定的提供商*和*可选地覆盖模型名称。如果任务的模型覆盖字段留空，则将使用为该任务选定提供商配置的默认模型。
- **为不同任务选择不同语言**:
    *   **禁用 (默认)**: 所有任务都使用单一的“输出语言”。
    *   **启用**: 允许您为每个任务（“添加链接”、“研究与摘要”、“从标题生成”、“总结为Mermaid图表”、“提取概念”）选择特定的语言。

<img width="817" height="428" alt="Multi-model" src="https://github.com/user-attachments/assets/85e6b854-c0ca-45cc-a55e-24638dceb120" />

### 语言架构（界面语言与任务输出语言）

- **界面语言**只控制插件界面文案（设置项、侧边栏按钮、提示、弹窗）。默认 `auto` 会跟随 Obsidian 当前界面语言。
- 区域/书写体系变体现在会优先映射到最接近的已发布语言目录，而不是直接回退到英文。例如，`fr-CA` 使用法语，`es-419` 使用西班牙语，`pt-PT` 使用葡萄牙语，`zh-Hans` 使用简体中文，`zh-Hant-HK` 使用繁体中文。
- **任务输出语言**控制模型生成内容的语言（添加链接、研究摘要、按标题生成、Mermaid 总结、概念提取、翻译目标）。
- **按任务语言模式**通过统一策略层解析每个任务的输出语言，避免分散在各模块中的语言分支造成行为漂移。
- **禁用自动翻译**后，非翻译任务会保留原文语言上下文；显式“翻译”任务仍按目标语言执行。
- Mermaid 相关生成链路与上述统一语言策略保持一致，并在开启时继续支持自动 Mermaid 修复。

### 稳定 API 调用设置

- 启用稳定 API 调用（重试逻辑）

  :

  - **禁用 (默认)**: 单个 API 调用失败将停止当前任务。
  - **启用**: 自动重试失败的 LLM API 调用（对于间歇性网络问题或速率限制很有用）。
  - **连接测试回退**: 即使普通调用当前没有预先开启稳定模式，Provider 的连接测试在首次遇到瞬时网络错误后也会切换到同一套重试序列。
  - **运行时传输回退（环境感知）**: 如果长耗时任务请求被 `requestUrl` 瞬时断开，Notemd 会先使用与当前环境匹配的回退传输重试同一次调用：桌面端走 Node `http/https`，非桌面环境走浏览器 `fetch`。该回退阶段现在会按协议解析各类流式输出，覆盖 OpenAI-compatible / Azure OpenAI 的 SSE、Anthropic Messages SSE、Google Gemini SSE，以及 Ollama 的 NDJSON，让慢速网关尽早返回 body 分片；其余直连的 OpenAI 风格 Provider 入口也会复用这条共享回退链路。
  - **OpenAI-compatible 稳定模式顺序**: 在稳定模式下，OpenAI-compatible 的单次调用会优先走 `直连流式`，失败后立即尝试 `直连非流式`，最后才走 `requestUrl`（必要时附带流式回退解析）。三段都失败后，才计入下一次稳定重试，避免某一种传输链路抖动时过早报错。

- **重试间隔（秒）**: (仅在启用时可见) 重试尝试之间等待的时间（1-300 秒）。默认值：5。

- **最大重试次数**: (仅在启用时可见) 最大重试尝试次数（0-10）。默认值：3。
- **API 错误调试模式**:
    *   **禁用 (默认)**: 使用标准的简洁错误报告。
    *   **启用**: 为所有 Provider 和任务（包括翻译、搜索和连接测试）激活详细的错误日志记录（类似 DeepSeek 的详细输出）。日志现在会包含 HTTP 状态码、原始响应文本、请求传输时间线、脱敏后的请求 URL/请求头、单次尝试耗时、响应头、部分响应体、已解析的部分流式输出与堆栈信息，对于排查 API 连接问题和上游网关重置尤其关键。
- **开发者模式**:
    *   **禁用 (默认)**: 隐藏开发者专用诊断控件，避免普通用户误操作。
    *   **启用**: 在设置页显示独立 Developer 诊断面板。
- **开发者提供商诊断（长请求）**:
    *   **诊断调用方式**: 可选择调用路径进行诊断。OpenAI-compatible Provider 额外支持强制 `直连流式`、`直连非流式`、`requestUrl-only`。
    *   **运行诊断**: 以当前调用方式执行一次长请求探针，并将完整报告 `Notemd_Provider_Diagnostic_*.txt` 写入仓库根目录。
    *   **运行稳定性测试**: 以当前调用方式执行可配置轮次（1-10）的重复调用，输出聚合稳定性报告。
    *   **诊断超时**: 可配置单次诊断超时（15-3600 秒）。
    *   **适用场景**: 当“测试连接”成功但真实长任务（例如慢网关下翻译）仍快速失败时，可快速定位链路问题。

<img width="805" height="187" alt="stable API calls" src="https://github.com/user-attachments/assets/936454a7-b657-413c-8a2a-13d517f9c519" />

### 常规设置

#### 处理文件输出

- 自定义处理文件的保存路径

  :

  - **禁用 (默认)**: 处理过的文件（例如 `YourNote_processed.md`）保存在与原始笔记*相同的文件夹*中。
  - **启用**: 允许您指定自定义保存位置。

- **处理文件文件夹路径**: (仅在启用上述选项时可见) 输入 vault 内的*相对路径*（例如 `Processed Notes` 或 `Output/LLM`），处理过的文件应保存在此路径。如果文件夹不存在，将自动创建。**请勿使用绝对路径（如 C:...）或无效字符。**

- 为“添加链接”使用自定义输出文件名

  :

  - **禁用 (默认)**: 由“添加链接”命令创建的处理文件使用默认的 `_processed.md` 后缀（例如 `YourNote_processed.md`）。
  - **启用**: 允许您使用下面的设置自定义输出文件名。

- 自定义后缀/替换字符串

  : (仅在启用上述选项时可见) 输入用于输出文件名的字符串。

  - 如果留**空**，原始文件将被处理后的内容**覆盖**。
  - 如果您输入一个字符串（例如 `_linked`），它将被附加到原始基本名称后（例如 `YourNote_linked.md`）。确保后缀不包含无效的文件名字符。

- 在添加链接时移除代码围栏

  :

  - **禁用 (默认)**: 添加链接时，代码围栏 **(`)\** 会保留在内容中，而 \**(`markdown)** 会被自动删除。
  - **启用**: 在添加链接之前从内容中移除代码围栏。

<img width="799" height="301" alt="Processed file output" src="https://github.com/user-attachments/assets/65d4e864-ff5f-402a-be90-e9c44b208903" />

#### 概念笔记输出

- 自定义概念笔记路径

  :

  - **禁用**: 禁用为 `[[链接的概念]]` 自动创建笔记。
  - **启用（默认）**: 允许您指定创建新概念笔记的文件夹。

- **概念笔记文件夹路径**: (仅在启用上述选项时可见) 输入 vault 内的*相对路径*（例如 `Concepts` 或 `Generated/Topics`），新概念笔记应保存在此路径。如果文件夹不存在，将自动创建。**如果启用了自定义，则必须填写。** **请勿使用绝对路径或无效字符。**

- **前置配置提示弹窗**: 对于 **处理文件/文件夹（添加链接）**、**提取概念** 以及包含这些步骤的工作流，如果当前没有正确启用并配置概念笔记路径，插件会弹出提示，提供 **进行配置**、**本次不提示**、**不再提示** 三个选项。

<img width="800" height="145" alt="concept note output" src="https://github.com/user-attachments/assets/d0338341-7d67-4472-964c-75a0992165b8" />

#### 概念日志文件输出

- 生成概念日志文件

  :

  - **禁用 (默认)**: 不生成日志文件。
  - **启用**: 处理后创建一个日志文件，列出新创建的概念笔记。格式如下： `生成 xx 个概念 md 文件 1. 概念1 2. 概念2 ... n. 概念n`

- 自定义日志文件保存路径

  : (仅在启用“生成概念日志文件”时可见)

  - **禁用 (默认)**: 日志文件保存在**概念笔记文件夹路径**（如果已指定）中，否则保存在 vault 根目录。
  - **启用**: 允许您为日志文件指定自定义文件夹。

- **概念日志文件夹路径**: (仅在启用“自定义日志文件保存路径”时可见) 输入 vault 内的*相对路径*（例如 `Logs/Notemd`），日志文件应保存在此路径。**如果启用了自定义，则必须填写。**

- 自定义日志文件名

  : (仅在启用“生成概念日志文件”时可见)

  - **禁用 (默认)**: 日志文件名为 `Generate.log`。
  - **启用**: 允许您为日志文件指定自定义名称。

- **概念日志文件名**: (仅在启用“自定义日志文件名”时可见) 输入所需的文件名（例如 `ConceptCreation.log`）。**如果启用了自定义，则必须填写。**

<img width="809" height="281" alt="Concept log file output" src="https://github.com/user-attachments/assets/eef6f5d5-592d-4b8f-84b1-7404521a6e9b" />

#### 提取概念任务
- **创建最简概念笔记**:
    - **开启（默认）**：新创建的概念笔记将只包含标题（例如 `# 概念`）。
    - **关闭**：概念笔记可能包含其他内容，例如“链接来源”反向链接（如果下面的设置未禁用）。
- **添加“链接来源”反向链接**:
    - **关闭（默认）**：在提取过程中，不会在概念笔记中添加指向源文档的反向链接。
    - **开启**：添加一个带有指向源文件反向链接的“链接来源”部分。
- **提取概念时替换同义词**:
    - **关闭（默认）**：保持现有提取提示不变。
    - **开启**：会在 **处理文件/文件夹（添加链接）** 与 **提取概念** 的提示前追加约束，尽量避免抽取同义词、语义相近核心概念或关键词近重复项。

#### 提取特定原始内容
-   **提取问题**: 输入您希望AI从笔记中逐字提取答案的问题列表（每行一个）。
-   **批量提取特定原始内容**: 除单文件命令外，侧边栏 / 工作流构建器现在也支持对选中文件夹中的全部 `.md` / `.txt` 文件执行同一套提取问题。
-   **将输出翻译为相应语言**:
    *   **关闭 (默认)**: 仅以原始语言输出提取的文本。
    *   **开启**: 以由此任务选择的语言附加提取文本的翻译。
-   **合并查询模式**:
    *   **关闭**: 单独处理每个问题（精度更高但API调用更多）。
    *   **开启**: 在单个提示中发送所有问题（更快且API调用更少）。
-   **自定义提取文本保存路径和文件名**:
    *   **关闭**: 保存到与原始文件相同的文件夹，后缀为 `_Extracted`。
    *   **开启**: 允许您指定自定义输出文件夹和文件名后缀。

#### 批量Mermaid修复
-   **启用Mermaid错误检测**:
    *   **关闭**: 处理后跳过错误检测。
    *   **开启（默认）**: 扫描处理后的文件以查找剩余的Mermaid语法错误，并生成 `mermaid_error_{foldername}.md` 报告。
-   **将存在Mermaid错误的文件移动到指定文件夹**:
    *   **关闭**: 有错误的文件保留在原位。
    *   **开启**: 将修复尝试后仍包含Mermaid语法错误的文件移动到专用文件夹以供手动审查。
-   **Mermaid错误文件夹路径**: (仅在启用上述选项时可见) 移动错误文件的文件夹。

#### 处理参数

- **启用批处理并行化**:
    - **禁用 (默认)**: 批处理任务（如“处理文件夹”或“从标题批量生成”）将逐个（串行）处理文件。
    - **启用**: 允许插件同时处理多个文件，这可以显著加快大型批处理作业的速度。
- **批处理并发数**: (仅在启用并行化时可见) 设置并行处理的最大文件数。较高的数字可以更快，但会消耗更多资源，并可能达到API速率限制。（默认值：1，范围：1-20）
- **批处理大小**: (仅在启用并行化时可见) 分组到单个批次中的文件数。（默认值：50，范围：10-200）
- **批处理间隔延迟（毫秒）**: (仅在启用并行化时可见) 处理每个批次之间的可选延迟（以毫秒为单位），这有助于管理API速率限制。（默认值：1000毫秒）
- **API 调用间隔（毫秒）**: 每个单独的 LLM API 调用之前和之后的最小延迟（以毫秒为单位）。对于低速率 API 或防止 429 错误至关重要。设置为 0 表示没有人为延迟。（默认值：500毫秒）
- **最大令牌数**: LLM 每个响应块应生成的全局最大令牌数。影响成本和细节。如果当前 provider 在高级设置中填写了“提供商输出 Token 覆盖上限”，则会优先使用该 provider 级上限。如果该项仍处于默认的自动托管基线，切换模型时也会自动更新为该模型已知的输出 Token 上限。（默认值：8192）
- **分块字数**: 发送给 LLM 的每个块的最大字数。影响大型文件的 API 调用次数。默认推荐值为 **最大令牌数** 的三分之一并向上取整；如果您尚未自定义该值，修改最大令牌数或切换到另一个已知上限模型时，插件会自动填入推荐分块值。（默认值：3000）
- **启用重复检测**: 切换对处理内容中重复单词的基本检查（结果在控制台中）。（默认值：启用）

<img width="795" height="274" alt="Processing Parameters   Language settings" src="https://github.com/user-attachments/assets/74e4af76-3333-48fc-bb86-0a3ee61825d1" />

#### 文件夹任务文件筛选
- **筛选模式**: 文件夹任务可选择不筛选，或按 `contains`、`regex`、`glob` 匹配文件。
- **匹配目标**: 可按文件 `relativePath` 或 `basename` 进行匹配。
- **子文件夹范围**: 每类文件夹任务都可保留兼容旧行为，或显式指定包含/排除子文件夹；Translate 默认仍保持“仅当前目录”，除非你主动覆盖。
- **开发者开关控制的高级模式**: Regex / glob 筛选、已保存文件筛选档案、子文件夹范围覆盖、preset chips 以及更复杂的 batch 文件夹弹窗默认都会隐藏。只有先开启 `Developer mode`，再在开发者设置中打开 `Advanced batch file selection`，这些高级控件和复杂弹窗才会出现；否则 batch 文件夹任务保持更简洁的 legacy 选择流程。

#### 本地知识检索
- **启用本地知识检索**:
    *   **关闭（默认）**: `从标题生成`、`从标题批量生成`、`研究与总结`、`生成图形` 不注入本地检索上下文。
    *   **开启**: 会从已配置的 Vault 相对文件/文件夹路径中索引 Markdown / Text 文件，并将最匹配的本地上下文注入上述任务。
- **默认知识库路径**: 每行一个 Vault 相对文件或文件夹路径。索引与检索均在插件本地运行，不依赖外部服务。
- **按任务覆盖知识库路径**: `从标题生成`、`从标题批量生成`、`研究与总结`、`生成图形` 都可以单独配置自己的文件/文件夹路径列表；留空时自动回退到默认知识库路径。
- **滑动窗口大小**: 控制每个命中点向前/向后合并同文件相邻章节的范围，再一起注入提示。
- **排除当前文件**: 避免把当前正在处理的文件再次检索回自己的提示上下文。

#### 设置重置
- **完全重置**: 将所有设置恢复为插件默认值。
- **部分重置**: 将非 Provider 设置恢复默认，同时保留 Provider 选择、模型和已保存的 Provider 配置。

#### 翻译
- **目标语言**：可选默认目标语言，命令时可覆盖。
- **翻译文件保存路径/后缀**：自定义翻译结果的保存路径和文件名后缀（Notemd: Translate Note/Selection）。
<img width="811" height="243" alt="translate" src="https://github.com/user-attachments/assets/57d21a72-e86c-4369-8be5-fd18cb734e2b" />

#### Mermaid 设置
- **Mermaid 输出文件夹**: 配置生成Mermaid图表文件的保存文件夹。如果留空，图表将保存在与原始笔记相同的文件夹中。
- **翻译总结为Mermaid输出**: 可选地将生成的Mermaid图表内容翻译成配置的目标语言。

#### 内容生成

- 在“从标题生成”中启用研究

  :

  - **禁用 (默认)**: “从标题生成”仅使用标题作为输入。
  - **启用**: 使用配置的**网络研究提供商**执行网络研究，并将研究结果作为上下文包含在基于标题生成的 LLM 提示中。

- **生成后自动修复Mermaid语法**:
    - **启用 (默认)**: 在处理、从标题生成、批量从标题生成、研究与摘要、总结为Mermaid图表、翻译等 Mermaid 相关流程结束后，自动执行 Mermaid 语法修复。
    - **禁用**: 不自动处理 Mermaid 输出，需要手动运行“批量Mermaid修复”或将其加入自定义工作流。

- 输出语言

  : (新增) 为“从标题生成”和“从标题批量生成”任务选择所需的输出语言。

  - **英语 (默认)**: 提示以英语处理和输出。
  - **其他语言**: 指示LLM以英语进行推理，但以您选择的语言 (例如 西班牙语、法语、简体中文、繁體中文、阿拉伯语、印地语等) 提供最终文档。

- 更改提示词

  : (新增)

  - **更改提示词**: 允许您更改特定任务的提示词。
  - **自定义提示词**: 输入您任务的自定义提示词。

- 为“从标题生成”使用自定义输出文件夹

  :

  - **禁用 (默认)**: 成功生成的文件将移动到相对于原始文件夹父目录的名为 `[原始文件夹名称]_complete` 的子文件夹中（如果原始文件夹是根目录，则为 `Vault_complete`）。
  - **启用**: 允许您为移动已完成文件的子文件夹指定自定义名称。

- **自定义输出文件夹名称**: (仅在启用上述选项时可见) 输入子文件夹所需的名称（例如 `Generated Content`, `_complete`）。不允许使用无效字符。如果留空，则默认为 `_complete`。此文件夹创建在原始文件夹的父目录内。

#### 一键工作流按钮

- **可视化工作流构建器**：无需手写 DSL，即可从内置动作创建、编辑和排序自定义工作流按钮。
- **自定义工作流 DSL**：高级用户仍可直接编辑文本定义。若 DSL 配置存在问题，插件会安全回退到默认工作流，并在设置/侧边栏中提示警告。
- **工作流错误策略**：
    - **遇错停止（默认）**：任一步骤失败后立即中止整个工作流。
    - **遇错继续**：继续执行后续步骤，并在结束时汇总失败次数。
- **内置默认工作流**：`One-Click Extract` 默认串联 `处理文件（添加链接）` -> `批量从标题生成内容` -> `批量Mermaid修复`。

#### 自定义提示词设置
此功能允许您覆盖发送给LLM的特定任务的默认指令（提示词），从而对输出进行精细控制。

-   **为特定任务启用自定义提示词**：
    *   **禁用（默认）**：插件对所有操作使用其内置的默认提示词。
    *   **启用**：激活为下面列出的任务设置自定义提示词的功能。这是此功能的主开关。

-   **为[任务名称]使用自定义提示词**：（仅<EFBFBD><EFBFBD>启用上述功能时可见）
    *   对于每个支持的任务（“添加链接”、“从标题生成”、“研究与摘要”、“提取概念”），您可以单独启用或禁用您的自定义提示词。
    *   **禁用**：此特定任务将使用默认提示词。
    *   **启用**：此任务将使用您在下方相应“自定义提示词”文本区域中提供的文本。

-   **自定义提示词文本区域**：（仅在启用任务的自定义提示词时可见）
    *   **默认提示词显示**：为方便您参考，插件会显示该任务通常使用的默认提示词。您可以使用**“复制默认提示词”**按钮复制此文本，作为您自己自定义提示词的起点。
    *   **自定义提示词输入**：您可以在此处编写自己的LLM指令。
    *   **占位符**：您可以在提示词中使用特殊的占位符，插件在将请求发送给LLM之前会将其替换为实际内容。请参考默认提示词以查看每个任务可用的占位符。常用占位符包括：
        *   `{TITLE}`：当前笔记的标题。
        *   `{RESEARCH_CONTEXT_SECTION}`：从网络研究中收集的内容。
        *   `{USER_PROMPT}`：正在处理的笔记内容。

<img width="794" height="174" alt="Content generation   output" src="https://github.com/user-attachments/assets/76d93942-980d-49ad-b9d4-1c73ea013d17" />

<img width="866" height="646" alt="Duplicate check scope   Custom prompt settings" src="https://github.com/user-attachments/assets/1b37a523-ef00-4e40-94a0-43bbe0c78572" />

#### 重复检查范围

- 重复检查范围模式

  : 控制将概念笔记文件夹中的笔记与哪些文件进行比较以查找潜在重复项。

  - **整个 Vault (默认)**: 将概念笔记与 vault 中的所有其他笔记（不包括概念笔记文件夹本身）进行比较。
  - **仅包含特定文件夹**: 仅将概念笔记与下面列出的文件夹中的笔记进行比较。
  - **排除特定文件夹**: 将概念笔记与*除*下面列出的文件夹中的笔记（以及概念笔记文件夹）之外的所有笔记进行比较。
  - **仅概念文件夹**: 仅将概念笔记与*概念笔记文件夹内的其他笔记*进行比较。这有助于查找纯粹在您生成的概念内部的重复项。

- **包含/排除文件夹**: (仅在模式为“包含”或“排除”时可见) 输入您要包含或排除的文件夹的*相对路径*，**每行一个路径**。路径区分大小写，并使用 `/` 作为分隔符（例如 `Reference Material/Papers` 或 `Daily Notes`）。这些文件夹不能与概念笔记文件夹相同或位于其内部。

#### 网络研究提供商

- **搜索提供商**: 在 `Tavily`（需要 API 密钥，推荐）和 `DuckDuckGo`（实验性，经常被搜索引擎阻止自动化请求）之间选择。用于“研究与摘要主题”和可选的“从标题生成”。
- **Tavily API 密钥**: (仅在选择 Tavily 时可见) 输入您从 [tavily.com](https://tavily.com/) 获取的 API 密钥。
- **Tavily 最大结果数**: (仅在选择 Tavily 时可见) Tavily 应返回的最大搜索结果数（1-20）。默认值：5。
- **Tavily 搜索深度**: (仅在选择 Tavily 时可见) 选择 `basic`（默认）或 `advanced`。注意：`advanced` 提供更好的结果，但每次搜索消耗 2 个 API 积分，而不是 1 个。
- **DuckDuckGo 最大结果数**: (仅在选择 DuckDuckGo 时可见) 要解析的最大搜索结果数（1-10）。默认值：5。
- **DuckDuckGo 内容获取超时**: (仅在选择 DuckDuckGo 时可见) 尝试从每个 DuckDuckGo 结果 URL 获取内容时等待的最大秒数。默认值：15。
- **最大研究内容令牌数**: 要包含在摘要提示中的组合网络研究结果（片段/获取的内容）的大致最大令牌数。有助于管理上下文窗口大小和成本。（默认值：3000）
<img width="810" height="278" alt="Web research provider" src="https://github.com/user-attachments/assets/be0280eb-bb4e-4db0-bf69-91da3f0fd3c0" />

#### 专注学习领域
-   **启用专注学习领域**:
    *   **禁用 (默认)**: 发送给LLM的提示词使用标准的通用指令。
    *   **启用**: 允许您指定一个或多个研究<E7A094><E7A9B6><EFBFBD>域，以提高LLM的上下文理解能力。
-   **学习领域**: (仅在启用上述选项时可见) 输入您的特定领域，例如“材料科学”、“高分子物理”、“机器学习”。这将在提示词的开头添加一行“相关领域: [...]”，帮助LLM为您的特定研究领域生成更准确、更相关的链接和内容。
<img width="595" height="143" alt="focused learning domain" src="https://github.com/user-attachments/assets/e8d5e407-d39d-4a21-a18f-446ca660276f" />

## 使用指南

### 快捷工作流与新版侧边栏

-   打开 Notemd 侧边栏后，可按核心处理、生成、翻译、知识整理、实用工具等分组查看内置动作。
-   侧边栏顶部的 **快捷工作流** 区域用于运行自定义多步骤按钮。
-   默认 **One-Click Extract** 会执行 `处理文件（添加链接）` -> `批量从标题生成内容` -> `批量Mermaid修复`。
-   每一步的状态、日志和失败信息都会显示在侧边栏中，底部固定区域会保护进度条与日志窗口不被展开的分组挤压。
-   进度卡片将状态文本、独立百分比标签与剩余时间分开展示，更便于快速判断当前执行情况；自定义工作流也可以在设置页中重新配置。

### 原始处理（添加维基链接）

**注意：** 这个会改写源文件的流程会继续严格限制在 `.md` 或 `.txt`。即使开发者设置中开启了 `放开输入文件限制`，这里也不会放开 PDF 或其他扩展格式，以保证添加链接和源文对照语义稳定。如果需要处理 PDF，请先用 [Mineru](https://github.com/opendatalab/MinerU) 等工具转成 Markdown。

1.  **侧边栏操作**：
    *   打开 Notemd 侧边栏（魔杖图标/命令面板）。
    *   打开目标`.md`或`.txt`文件。
    *   点击“处理文件（添加链接）”(Notemd: Process Current File)。
    *   文件夹处理：点击“处理文件夹（添加链接）”(Notemd: Process Folder)，选择文件夹并点击“处理”。
    *   进度实时显示，可随时取消任务（侧边栏按钮）。
    *   *批量处理文件在后台执行，不会打开编辑器。*

2.  **命令面板操作**（`Ctrl+P` 或 `Cmd+P`）：
    *   单文件：打开后运行 `Notemd: 处理当前文件 (Notemd: Process Current File)`。
    *   文件夹：运行 `Notemd: 处理文件夹 (Notemd: Process Folder)`，选择目标文件夹。批量处理不打开编辑器。
    *   进度弹窗可随时取消。
    *   *插件自动移除内容开头`\boxed{`和结尾`}（如有）再保存。*

### 新功能（翻译、网络研究与内容生成）

1.  **总结为Mermaid图表**：
    *   打开要总结的笔记。
    *   运行命令 `Notemd: 总结为Mermaid图表` (通过命令面板或侧边栏按钮)。
    *   插件将生成一个带有Mermaid图表的新笔记。

2.  **翻译笔记/选区**：
    *   选中文本可仅翻译选区，无选区则翻译全文。
    *   运行 `Notemd: 翻译笔记/选区 (Notemd: Translate Note/Selection)`。
    *   弹窗可确认/修改目标语言（默认使用设置）。
    *   翻译内容保存到指定路径并在原文右侧新窗格打开。
    *   任务可随时取消。

3.  **批量翻译**：
    *   从命令面板运行 `Notemd: 批量翻译文件夹` 并选择一个文件夹，或在文件浏览器中右键单击一个文件夹并选择“批量翻译此文件夹”。
    *   插件将翻译所选文件夹中的所有 Markdown 文件。
    *   翻译后的文件将保存到配置的翻译路径中，但不会自动打开。
    *   此过程可以通过进度模式取消。

3.  **研究与摘要主题**：
    *   选中文本或用笔记标题作为搜索主题。
    *   运行 `Notemd: 研究和摘要主题 (Notemd: Research and Summarize Topic)`。
    *   配置的搜索服务与LLM自动协作，结果附加到当前笔记。
    *   任务可随时取消。
    *   *DuckDuckGo 可能因反爬机制失败，推荐Tavily。*

4.  **从标题生成内容**：
    *   打开任意笔记（可为空）。
    *   运行 `Notemd: 从标题生成内容 (Notemd: Generate Content from Title)`。
    *   LLM根据标题生成内容并替换原文。
    *   可选先自动研究，丰富上下文。
    *   任务可随时取消。

5.  **批量从标题生成内容**：
    *   运行 `Notemd: 从标题批量生成内容 (Notemd: Batch Generate Content from Titles)`。
    *   选择要处理的文件夹，自动跳过已完成文件。
    *   成功处理的文件自动移动到指定“完成”子文件夹。
    *   任务可随时取消。

6.  **提取概念（纯模式）**:
    *   此功能允许您从文档中提取概念并创建相应的概念笔记，而*不*更改原始文件。它非常适合从一组文档中快速填充您的知识库。
    *   **单个文件**：打开一个文件，从命令面板运行 `Notemd: 提取概念（仅创建概念笔记）` 命令，或单击侧边栏中的 **“提取概念（当前文件）”** 按钮。
    *   **文件夹**：从命令面板运行 `Notemd: 批量提取概念` 命令，或单击侧边栏中的 **“提取概念（文件夹）”** 按钮，然后选择一个文件夹来处理其中的所有笔记。
    *   插件将读取文件，识别概念，并在您指定的 **概念笔记文件夹** 中为它们创建新笔记，而原始文件保持不变。

7.  **创建维基链接并从选区生成笔记**：
    *   这个强大的命令简化了创建和填充新概念笔记的过程。
    *   在编辑器中选择一个词或短语。
    *   运行命令 `Notemd: 创建维基链接并从选区生成笔记` (建议为此分配一个快捷键，如 `Cmd+Shift+W`)。
    *   插件将会：
        1.  将您选择的文本替换为 `[[维基链接]]`。
        2.  检查您的 **概念笔记文件夹** 中是否已存在该标题的笔记。
        3.  如果存在，它会向当前笔记添加一个反向链接。
        4.  如果不存在，它会创建一个新的空笔记。
        5.  然后，它会自动对新的或现有的笔记运行 **“从标题生成内容”** 命令，用AI生成的内容填充它。

8.  **提取概念并生成标题**：
    *   该命令将两个强大的功能链接在一起，以实现简化的工作流程。
    *   从命令面板运行命令 `Notemd: 提取概念并生成标题` (建议为此分配一个快捷键)。
    *   插件将会：
        1.  首先，对当前活动文件运行 **“提取概念（当前文件）”** 任务。
        2.  然后，它将自动在您设置为 **概念笔记文件夹路径** 的文件夹上运行 **“批量从标题生成”** 任务。
    *   这使您可以首先从源文档中提取新概念来填充您的知识库，然后立即在一个步骤中用AI生成的内容来充实这些新的概念笔记。

### 实用工具

1.  **检查重复项**：
    *   打开目标`.md`或`.txt`文件。
    *   运行 `Notemd: 检查当前文件中的重复项 (Notemd: Check for Duplicates in Current File)`。
    *   结果输出到开发者控制台和通知栏/侧边栏。

2.  **测试LLM连接**：
    *   运行 `Notemd: 测试LLM连接 (Notemd: Test LLM Connection)`。
    *   验证当前激活服务商的API设置，结果显示在通知栏和侧边栏。

3.  **批量Mermaid修复**：
    *   运行 `Notemd: 批量修复Mermaid语法 (Notemd: Batch Fix Mermaid Syntax)`。
    *   对用户选择的文件夹内的所有Markdown文件应用Mermaid和LaTeX语法校正。
    *   **错误报告**: 生成 `mermaid_error_{foldername}.md` 报告，列出处理后仍包含潜在Mermaid错误的文件。
    *   **移动错误文件**: 可选地将检测到错误的文件移动到指定文件夹以供手动审查。
    *   **高级修复模式**: 包含针对包含空格、特殊字符或嵌套括号的未加引号节点标签的稳健修复（例如，将 `Node[标签 [文本]]` 转换为 `Node["标签 [文本]"]`）。

4.  **检查并删除重复概念笔记**：
    *   配置好概念笔记文件夹后运行该命令。
    *   运行 `Notemd: 检查并删除重复概念笔记 (Notemd: Check and Remove Duplicate Concept Notes)`。
    *   自动检测并提示所有潜在重复项，需手动确认删除。
    *   进度与结果显示在侧边栏/通知栏。

5.  **提取特定原始内容**:
    *   在“提取特定原始内容”下的设置中配置您的问题。
    *   使用侧边栏中的“提取特定原始内容”按钮来处理当前活动文件。
    *   使用侧边栏或工作流中的“批量提取特定原始内容”来处理所选文件夹中的全部支持文件。
    *   **合并模式**: 通过在一个提示中发送所有问题来加快处理速度。
    *   **翻译**: 可选地将提取的文本翻译为您配置的语言。
    *   **自定义输出**: 配置提取文件的保存位置和方式。

## 支持的LLM提供商

| 提供商             | 类型   | 需要 API 密钥        | 说明                                                              |
|--------------------|--------|----------------------|-------------------------------------------------------------------|
| DeepSeek           | 云     | 是                   | DeepSeek 原生端点，已处理 reasoning 模型差异                      |
| Qwen               | 云     | 是                   | 阿里云百炼 DashScope 兼容模式预设，适合 Qwen / QwQ               |
| Qwen Code          | 云     | 是                   | 阿里云百炼面向编码模型的独立预设，适合 Qwen coder 系列            |
| Doubao             | 云     | 是                   | 火山方舟 Ark 兼容模式预设，模型字段通常填写 Endpoint ID           |
| Moonshot           | 云     | 是                   | Moonshot / Kimi 官方端点                                          |
| Xiaomi MiMo        | 云     | 是                   | Xiaomi MiMo 的 OpenAI-compatible 端点，适合聊天、编码与多模态模型 |
| GLM                | 云     | 是                   | 智谱 BigModel 官方 OpenAI-compatible 端点                         |
| Z AI               | 云     | 是                   | Z AI 国际站 GLM/Zhipu OpenAI-compatible 端点，与 `GLM` 预设互补   |
| MiniMax            | 云     | 是                   | MiniMax 官方 chat-completions 端点                                |
| Huawei Cloud MaaS  | 云     | 是                   | 华为云 ModelArts MaaS OpenAI-compatible 端点，适合托管模型        |
| Baidu Qianfan      | 云     | 是                   | 百度千帆官方 OpenAI-compatible 端点，适合 ERNIE 等模型            |
| SiliconFlow        | 云     | 是                   | SiliconFlow 官方 OpenAI-compatible 端点，适合托管开源模型         |
| OpenAI             | 云     | 是                   | 支持 GPT 与 o 系列模型                                            |
| Anthropic          | 云     | 是                   | 支持 Claude 系列                                                  |
| Google             | 云     | 是                   | 支持 Gemini 系列                                                  |
| Mistral            | 云     | 是                   | 支持 Mistral / Codestral 系列                                    |
| Azure OpenAI       | 云     | 是                   | 需要 Endpoint、API Key、Deployment Name 和 API Version            |
| OpenRouter         | 网关   | 是                   | 通过 OpenRouter 模型 ID 访问多家提供商                            |
| xAI                | 云     | 是                   | Grok 原生端点                                                     |
| Groq               | 云     | 是                   | 面向托管开源模型的高速 OpenAI-compatible 推理端点                 |
| Together           | 云     | 是                   | 面向托管开源模型的 OpenAI-compatible 端点                         |
| AIHubMix           | 网关   | 是                   | 带专用 registry 发现的托管多提供商网关预设                      |
| GitHub Models      | 网关   | 是                   | 带 hosted catalog 发现的 GitHub 模型网关预设                    |
| PPIO               | 网关   | 是                   | 带 chat/embedding/reranker 有界发现的多提供商网关预设           |
| OVMS               | 本地   | 可选                 | 带本地有界模型发现的 OpenVINO Model Server 预设                 |
| Fireworks          | 云     | 是                   | OpenAI-compatible 推理端点                                        |
| LiteLLM            | 网关   | 可选                 | 自托管 OpenAI-compatible 代理预设；默认本地端点为 `http://localhost:4000/v1` |
| New API            | 网关   | 可选                 | 自托管 OpenAI-compatible 网关预设                                |
| Nebius             | 云     | 是                   | Nebius AI Studio 的 OpenAI-compatible 端点                        |
| Cerebras           | 云     | 是                   | Cerebras Cloud 的 OpenAI-compatible 高速推理端点                 |
| Hugging Face       | 网关   | 是                   | Hugging Face 托管推理路由预设                                     |
| Vercel AI Gateway  | 网关   | 是                   | Vercel 多提供商网关预设，并带专用模型发现实现                    |
| Requesty           | 网关   | 是                   | 单一 API Key 对接多提供商路由                                     |
| OpenAI Compatible  | 网关   | 可选                 | 通用预设，可接 LiteLLM、vLLM、Perplexity、Vercel AI Gateway 等    |
| LMStudio           | 本地   | 可选（`EMPTY`）      | LM Studio 本地 OpenAI-compatible 服务                             |
| Ollama             | 本地   | 否                   | Ollama 本地原生服务                                               |

*本地服务商请确保服务器已启动且 Base URL 配置正确。*
*OpenRouter 与 Requesty 请使用网关要求的完整/带前缀模型 ID（例如 `google/gemini-flash-1.5` 或 `anthropic/claude-3-7-sonnet-latest`）。*
*`Doubao` 预设通常要求在模型字段中填写 Ark Endpoint/Deployment ID，而不是直接填写模型家族名。设置页现在会在仍使用默认占位值时发出警告，并阻止连接测试，直到你替换为真实 Endpoint ID。*
*`Z AI` 面向国际 `api.z.ai` 线路，而 `GLM` 继续保留中国大陆 BigModel 入口。请根据账户区域选择对应预设。*
*中国区兼容协议预设默认使用 chat-first 测试，这样可以同时验证 API Key、模型名或部署 ID 是否真正可用。*
*`Vercel AI Gateway` 的模型发现现在会有界合并官方 `/v1/models` 目录与 `v3/ai/config`，而不是把它误当成普通 generic OpenAI-compatible `/models`。*
*`Azure OpenAI` 由于 deployment-mode endpoint 依赖 deployment name，当前仍保持 manual-first。`OpenRouter` 现在会有界合并 chat 与 embedding catalog；`Hugging Face` 现已接入有界的 OpenAI-compatible `/models` 发现路径；`LiteLLM` 现在会有界合并 `/models` 与 `/model/info`，`Huawei Cloud MaaS` 走专用 `v2/models` 模型注册表接口，`AIHubMix` 走其托管 `/api/v1/models` registry，`GitHub Models` 走有界 `catalog/models` + `/v1/models` 双源合并，`PPIO` 走有界的 chat + embedding + reranker 三路发现，`OVMS` 优先走当前本地 `/v3/models` 并在必要时回退到 legacy `/v1/config`，`New API` 复用共享的有界 OpenAI-compatible `/models` 路径，而通用 `OpenAI Compatible` 预设现在也会先把 OpenRouter / Requesty / Together / Huawei Cloud MaaS / Vercel AI Gateway / `AIHubMix` / `GitHub Models` / `PPIO` / 本地 LiteLLM 风格代理 / OVMS 风格本地 `/v3` 端点这类已知 host 自动解析到对应的有界发现 family，再回退到普通 `/models` 请求；共享归一化也允许用户直接填 `/responses`、`/chat/completions`、`/models` 这类端点形态。当它指向 OpenAI、DashScope/Qwen、Xiaomi MiMo、Fireworks、Hugging Face 这类已知可信官方 host 时，bare model ID 现在也会复用上游 provider 的已知 token-cap 元数据。*
*`OpenAI Compatible` 预设用于自定义网关与代理，请按对应服务文档填写 Base URL、鉴权方式和模型 ID。*

## 网络使用与数据处理

Notemd 在本地 Obsidian 运行，但部分功能会发起外部网络请求。

### LLM 提供商调用（可配置）

- 触发场景：处理文件、内容生成、翻译、研究总结、Mermaid 总结，以及连接测试/开发者诊断。
- 请求目标：你在 Notemd 设置中配置的 Provider Base URL。
- 发送数据：完成任务所需的 prompt 与内容片段。
- 数据说明：API Key 保存在本地插件配置中，并由你的设备发起签名请求。

### 网页研究请求（可选）

- 触发场景：开启网页研究并选择搜索提供商时。
- 请求目标：Tavily 或 DuckDuckGo。
- 发送数据：你的查询词与必要请求元数据。

### 开发者诊断与调试日志（可选）

- 触发场景：开启 API 调试模式或执行开发者诊断动作。
- 落地位置：保险库根目录（例如 `Notemd_Provider_Diagnostic_*.txt`、`Notemd_Error_Log_*.txt`）。
- 风险提示：日志可能包含请求/响应片段，对外分享前请先审查并脱敏。

### 本地存储

- 插件配置保存在 `.obsidian/plugins/notemd/data.json`。
- 生成文件、报告和可选日志根据你的设置保存在保险库内。

## 故障排除

### 常见问题
- **插件未加载**：确保`manifest.json`、`main.js`、`styles.css`均放置在 `<保险库>/.obsidian/plugins/notemd/` 并重启Obsidian。启动异常可通过开发者控制台查看。
- **处理失败/API错误**：
    1. 文件必须为`.md`或`.txt`格式；
    2. “测试LLM连接”命令可验证API设置（Notemd: Test LLM Connection）；
    3. 检查API Key、Base URL、模型名等参数是否填写正确；
    4. 本地模型需确保服务端已启动，Base URL无误；
    5. 云端服务需保证网络连接正常；
    6. 单文件处理失败可查看开发者控制台详细信息；
    7. 批量处理失败可查看保险库根目录的`error_processing_filename.log`日志。
    8. 自动错误日志：若任务失败，插件会在仓库根目录生成 `Notemd_Error_Log_[Timestamp].txt`，其中包含错误信息、堆栈与会话日志。开启“API 错误调试模式”后，该日志会包含更完整的 API 调试细节。
    9. 真实 Endpoint 长请求诊断（开发者）：
        - 插件内路径（建议先用）：进入 **设置 -> Notemd -> 开发者 Provider 诊断（长请求）**，对活动 Provider 执行运行时探针，并在仓库根目录生成 `Notemd_Provider_Diagnostic_*.txt` 报告。
        - CLI 路径（在 Obsidian 运行时之外）：若需要对真实端点执行 buffered 与 streaming 的可重复对照，可使用内置 Node 诊断脚本：
        ```bash
        npm run diagnose:llm -- \
          --transport openai-compatible \
          --provider-name OpenRouter \
          --base-url https://openrouter.ai/api/v1 \
          --api-key "$OPENROUTER_API_KEY" \
          --model anthropic/claude-3.7-sonnet \
          --prompt-file ./tmp/prompt.txt \
          --content-file ./tmp/content.txt \
          --mode compare \
          --timeout-ms 360000 \
          --output ./tmp/openrouter-diagnostic.txt
        ```
        该报告会记录每次尝试的 `First Byte`、`Duration`、脱敏后的请求信息、响应头、原始/部分响应体、已解析的流式片段以及传输层失败点，便于定位超时、断连与网关行为。
- **LM Studio/Ollama 连接问题**：
    *   **测试连接失败**：确保本地服务器（LM Studio 或 Ollama）正在运行，并且已加载/可用正确的模型。
    *   **CORS 错误（Windows上的Ollama）**：如果在 Windows 上使用 Ollama 时遇到 CORS（跨源资源共享）错误，您可能需要设置 `OLLAMA_ORIGINS` 环境变量。您可以在启动 Ollama 之前，在命令提示符中运行 `set OLLAMA_ORIGINS=*` 来实现。这允许来自任何来源的请求。
    *   **在 LM Studio 中启用 CORS**：对于 LM Studio，您可以直接在服务器设置中启用 CORS，如果 Obsidian 在浏览器中运行或具有严格的来源策略，这可能是必需的。
- **文件夹创建失败**：请确保设置中保存路径为相对路径，且不包含无效字符（如\* " \ / < > : | ? # ^ [ ] 等）。
- **性能问题**：大文件或批量处理可适当调低分块字数，或更换LLM模型。
- **链接质量问题**：可尝试不同模型或温度设置改善效果。

## 贡献

欢迎任何形式的贡献！请参考GitHub项目说明: [https://github.com/Jacobinwwey/obsidian-NotEMD](https://github.com/Jacobinwwey/obsidian-NotEMD)

## 维护者文档

- [发布流程（英文）](./docs/maintainer/release-workflow.md)
- [发布流程（简体中文）](./docs/maintainer/release-workflow.zh-CN.md)
- [CLI 能力矩阵（英文）](./docs/maintainer/notemd-cli-capability-matrix.md)
- [CLI 能力矩阵（简体中文）](./docs/maintainer/notemd-cli-capability-matrix.zh-CN.md)
- 仓库内维护者 CLI 帮助：`npm run cli:help`
- 仓库内维护者调用示例：`npm run cli:invoke -- --vault docs --operation content.split-note-by-chapters --input-json '{"sourcePath":"index.zh-CN.md","splitHeadingLevel":"h2"}' --pretty`
- 对 `--vault docs` 而言，JSON 里的路径都必须是 vault-relative；应使用 `index.zh-CN.md`、`maintainer`，不要写成 `docs/index.zh-CN.md` 或 `docs/maintainer`。
- 当前 public-safe export 命令刻意收敛为：脱敏 provider 导出、capability manifest 导出、invocation contract 导出、public-surface 导出。

## 许可证

MIT许可证 - 详情请见[LICENSE](LICENSE)。

---

*Notemd v1.9.4 - 用AI提升你的Obsidian知识图谱。*

<!-- repo-chronicle:start -->
## 发展编年史

这个季度版编年史保留了 [repo-saga](https://github.com/teee32/repo-saga) 的原始视觉样式，而且季度切分现在直接由 repo-saga 自身生成。

![Notemd Development Chronicle](./docs/repo-saga/notemd-development-history.zh.svg)

_最近一次已针对发布 tag `1.9.4` 于 2026-07-21 刷新。 最新提交日期：2026-07-21。_
<!-- repo-chronicle:end -->


## Star History

<a href="https://www.star-history.com/?repos=Jacobinwwey%2Fobsidian-NotEMD&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Jacobinwwey/obsidian-NotEMD&type=date&theme=dark&legend=top-left&sealed_token=Y32J_ehSQhPEtMK06bJeXYXBkFZbjjUR6tkogZgP92_f34InJDA7n9xcMmttFtW0o52nbKnU24nByb7DCiBnOrP2MOwevXU-so8BYLISzUsdeSUQRIOYg_lFXml_9MakEXjFEQStXFh7fUnsSXyIEq55QSTYNcbDOGF0k66bWhT1IyrZLnG26lJ-Mvbg" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Jacobinwwey/obsidian-NotEMD&type=date&legend=top-left&sealed_token=Y32J_ehSQhPEtMK06bJeXYXBkFZbjjUR6tkogZgP92_f34InJDA7n9xcMmttFtW0o52nbKnU24nByb7DCiBnOrP2MOwevXU-so8BYLISzUsdeSUQRIOYg_lFXml_9MakEXjFEQStXFh7fUnsSXyIEq55QSTYNcbDOGF0k66bWhT1IyrZLnG26lJ-Mvbg" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Jacobinwwey/obsidian-NotEMD&type=date&legend=top-left&sealed_token=Y32J_ehSQhPEtMK06bJeXYXBkFZbjjUR6tkogZgP92_f34InJDA7n9xcMmttFtW0o52nbKnU24nByb7DCiBnOrP2MOwevXU-so8BYLISzUsdeSUQRIOYg_lFXml_9MakEXjFEQStXFh7fUnsSXyIEq55QSTYNcbDOGF0k66bWhT1IyrZLnG26lJ-Mvbg" />
 </picture>
</a>