Vortelyn NoteBridge for Joplin

在 VS Code 中浏览、编辑和管理 Joplin 笔记，支持本机客户端和自建 Joplin Server 直连。

主要功能

• 笔记浏览：通过笔记本、全部笔记、搜索、标签和废纸篓五个视图查找内容。
• 富文本写作：默认直接编辑排版后的文字；分组工具栏提供标题、加粗、斜体、删除线、高亮、列表、任务、引用和链接，同页切换即时编辑、阅读和源码。
• 主题与目录：选择跟随系统、深色或浅色主题；显示标题大纲并点击跳转。13 种阅读样式自动记住，新增 Orange 暖橙；菜单和工具栏支持顶部一行/两行、左侧和右上角浮动。
• 临时标签：单击笔记临时查看，单击下一篇替换未修改的预览；编辑或双击后固定。可在设置关闭临时标签或树中双击固定。
• 代码复制与提示块：代码块右上角显示“复制”；顶部及编辑器右键可在当前光标插入备注、提示、警告、重要、危险、示例和引用提示块。
• 文件导出：顶部或右键“导出笔记”提供 PDF、Word、HTML 和 Markdown，使用当前编辑内容，无需先保存笔记。PDF 自动使用本机 Edge 或 Chrome，可在设置指定浏览器路径；PDF 和 HTML 保留提示块、公式及 Mermaid 渲染。Word 为可编辑 DOCX，采用 A4 排版，支持原生列表编号、续段、提示块、重复表头及 PNG/JPEG/GIF 图片；公式和 Mermaid 保留源码，其余图片格式保留说明文字。导出后可用系统默认应用打开文件，或打开所在文件夹。HTML 将附件嵌入文件；Markdown 保留原始 Joplin 资源引用。
• 日历与日记：侧栏分别提供笔记日历和日记。笔记可按创建或修改日期查看，日记按标题中的日期查看，普通日历排除 Journal 中的日记。命令“打开 / 创建今日日记”或日记日历中的“写日记”复用现有 Journal/年/月/日期 目录；重复执行打开已有日记。设置 journalTemplate 可修改新日记模板。
• 日记访问锁：日记视图可设置密码、解锁和锁定；默认不设置密码。密码使用加盐哈希保存于本机安全凭据存储，重新连接后需再次解锁。锁定会关闭已保存的日记标签页，并阻止插件和 AI 接口读取日记正文；有未保存编辑时先提示保存。此功能仅约束本机 NoteBridge，其他 Joplin 客户端和服务器仍保存可读原文，不是端到端加密；其他电脑需单独设置。
• 图片与附件：Ctrl+V 粘贴剪贴板图片，拖放或选择文件，图片、附件和 draw.io 均插入当前光标或选区；支持 Admonition、公式、Mermaid、表格、脚注和折叠内容的渲染。
• 服务器直连：未安装 Joplin 桌面端时，可登录自建 Joplin Server，浏览、修改并同步笔记及附件。
• 自动更新：默认每 3 秒检查其他窗口已保存到 Joplin 的笔记变化，切回窗口或笔记时立即检查；未保存的编辑会保留并提示冲突。
• 笔记整理：新建顶层或子笔记本后自动定位；支持重命名、移动、笔记多选删除和整本移入废纸篓。
• 标签管理：新建、查找、重命名和删除标签；在笔记标签选择框输入名称，可直接创建不存在的标签并勾选添加。
• 废纸篓：查看已删除的笔记本和笔记，只读查看内容，并恢复原有层级和笔记。
• 灵活排序：目录、笔记和标签分别设置按名称或修改时间升序、降序排列。笔记本名称及 Joplin Server 列表按编号自然排序（1.1 → 1.2 → 1.10），Server 分页加载保持同一顺序。
• 源码与样式：菜单、工具栏或笔记右键可复制完整源码，包含未保存修改。内置简洁、书页、墨绿、学术、Orange 暖橙等 13 种渲染样式，可独立选择深浅色主题；窄窗口通过“更多工具”访问其余操作。
• 聊天协作：将笔记或笔记本添加为聊天参考，通过工具读取、查找和管理笔记。
• 快速保存：将编辑器选区保存为新笔记，或将聊天总结保存到指定笔记本。
• 双语界面：支持简体中文和英文。

开始使用

需要 VS Code 1.130.0 或更高版本。以下连接方式任选其一。

使用本机 Joplin 客户端

1. 在 Joplin 的设置中启用 Web Clipper 服务。
2. 打开 VS Code 侧栏的 Joplin，点击顶部齿轮 连接设置。
3. 选择本机客户端，输入 Joplin Web Clipper 授权令牌，点击 保存并连接。
4. 展开笔记本并打开笔记，直接编辑正文，保存后写回 Joplin。

默认服务地址为 http://127.0.0.1:41184。如果 Joplin 使用其他端口，可在 VS Code 设置中修改 joplinWorkbench.baseUrl。扩展连接本机服务，使用时请保持 Joplin 运行。

授权令牌由 VS Code 安全存储；后续打开侧栏会使用已保存的令牌连接。手动断开后，需要再次点击连接。

可通过 joplinWorkbench.autoSyncIntervalSeconds 调整自动检查间隔，设为 0 可关闭。手动刷新也会更新已打开且未修改的笔记。其他设备上的修改需要先经 Joplin 同步到本机；尚未保存的编辑不会发送到其他窗口。

Joplin 侧栏顶部和 VS Code 底部状态栏显示加载、同步及已读取数量。点击底部的 Joplin 状态或侧栏齿轮，进入 加载与同步：查看最近成功同步时间、下次自动检查倒计时及错误原因；可立即同步、停止本次后台同步，或修改同步间隔。默认 3 秒，保留已有配置；支持 0–300 秒，0 为仅手动。频次修改立即生效，不重新登录。保存笔记会立即上传，自动同步间隔控制的是检查远端变化的频次。

直接连接自建 Joplin Server

点击 Joplin 侧栏顶部齿轮 连接设置，选择 自建 Joplin Server，在同一页填写服务器地址、账号邮箱和密码，然后点击 保存并连接。也可在 VS Code 设置中搜索 @ext:vortelyn.vortelyn-notebridge，点击连接选项下的 打开连接设置；命令面板提供 Joplin: 连接设置。地址有子路径时需填写完整。

测试连接 只验证登录和同步格式，不修改已保存配置，不读取笔记正文，也不切换当前连接。保存设置 可先保存连接资料，稍后再连接。密码单独保存在 VS Code 安全凭据存储中，不写入设置文件；相同服务器和账号可以留空复用，切换服务器或账号需重新填写。后续自动使用已保存的连接资料。切回桌面客户端也在此页面选择。

连接被拒绝时，页面显示失败的 API 路径、HTTP 状态及经过脱敏的服务器原因。网页登录成功仍可能遇到 API 会话、账号权限或反向代理限制，可点击 打开服务器登录页 对照检查；不要将浏览器会话令牌填写为密码。已过期的 API 会话在读取时自动重新登录一次。

首次连接会读取服务器上的同步条目，页面显示当前阶段、分页和已读取数量。笔记较多时需要等待首次加载完成；可随时取消。遇到 HTTP 429 时按服务器要求倒计时，期间暂停登录，结束后可手动重试；切换侧栏不会自动重试失败的登录。HTTPS 保持证书校验，证书错误会单独显示。

首次同步完成后会保存按账号隔离的加密本地缓存。后续重连从已保存的同步游标检查变化，未变化的条目无需重新下载；同时发起的同步及短时间内的列表刷新合并检查。缓存损坏或服务器要求重建游标时会重新完整读取。缓存只用于加速，保存笔记仍校验远端版本，网络中断时不会覆盖服务器内容。

直连适用于已有的、已完成初始化的 Joplin 同步格式 3 账号，当前支持未启用端到端加密的内容。修改保存后直接写到服务器；其他设备下次同步时获得更新。连接期间自动拉取服务器变化；网络不可用时保留未保存编辑并报告失败，不在离线状态排队写入。共享内容目前只读。服务器直连搜索按空格分隔关键词，匹配标题和正文；桌面模式保留 Joplin 原有搜索语法。

预览、图片与附件

默认单击笔记使用 VS Code 临时标签；下一篇替换未修改的预览，编辑、双击笔记树或右键“固定笔记标签”后保留。joplinWorkbench.enablePreviewTabs 可关闭此行为；使用临时标签还需开启 VS Code 的 workbench.editor.enablePreview。joplinWorkbench.pinOnDoubleClick 控制树中的双击固定；双击顶部标签遵循 VS Code 本身的规则。已有固定标签不会被自动关闭。

默认顶部两行：文件/编辑/插入/视图菜单 + 快捷工具栏。在笔记的 视图 菜单中即可调整，也可在 VS Code 设置搜索 @ext:vortelyn.vortelyn-notebridge：showToolbar 显示快捷工具栏，toolbarPosition 选择 top、side 或 floating，toolbarRows 选择 1 或 2（顶部适用）。关闭快捷工具栏后菜单仍然可用。右上角浮动模式预留正文边距，默认收起；悬停展开完整的多行面板，文字按钮按文件、格式、图片图表、提示块和外观等分组排列，功能不再收进“更多工具”。小窗口可在面板内部滚动。移开收起，单击小按钮保持展开，点击正文或按 Escape 收起。键盘焦点停在菜单中时也保持展开。正文上方的保存状态和操作说明不再常驻显示；错误仍会显示。

Orange 暖橙使用暖色纸张、珊瑚橙标题、柔和引用和交替表格底色，同时适配深浅色；是为当前编辑器编写的样式，风格参考 Typora OrangeHeart 主题，并非加载其完整 CSS。

Markdown 笔记默认打开“富文本”，可直接编辑排版后的文字。顶部工具栏包含标题 H1–H6、加粗、斜体、删除线、高亮、行内代码、列表、任务复选框、引用、代码块、分隔线、链接和插入操作。“富文本／即时编辑／阅读／源码”在同一页切换并保留光标；阅读时双击段落回到对应位置编辑。按 Ctrl+S 保存，Ctrl+Z 撤销，Ctrl+Shift+Z 或 Ctrl+Y 重做。右侧 ↗ 可打开 VS Code 原生源码编辑器。

左侧大纲按钮显示或收起标题目录，点击目录可跳转到对应位置；主题下拉框提供跟随操作系统、深色、浅色。两项选择分别保存到 joplinWorkbench.showOutline 和 joplinWorkbench.editorTheme。

joplinWorkbench.defaultNoteView 可设为 rich（默认）、live（即时 Markdown）、preview（阅读）或 source（VS Code 原生源码）。已配置的默认视图会保留，可在设置中改为 rich。HTML 笔记默认阅读，通过源码编辑并保留 HTML 格式。

富文本编辑基于开源 ProseMirror；未修改的块保留原始 Markdown。Mermaid、Admonition、公式、表格、HTML 和未识别语法使用保留原文的特殊块，可点击“编辑此块源码”定位修改，再切回富文本查看效果。表格目前通过源码修改单元格；不执行 Joplin 插件脚本，也不保证任意第三方插件都能渲染。

图片和文件按 Joplin 原生资源方式上传，正文使用 :/资源ID 引用。插入后保存笔记（Ctrl+S 或 VS Code 自动保存）：直连 Server 会上传正文，其他设备同步后可看到图片；桌面模式由 Joplin 客户端继续同步。附件不依赖当前电脑的临时路径。

插入图片、文件、Mermaid 和 draw.io 使用操作开始时的光标或选区；拖放使用落点。图片会作为独立段落显示，避免与正文粘连。在阅读页可双击目标段落后粘贴，也可以使用此前记住的编辑位置。文件选择和图表命名弹窗不会把位置改到末尾。每次最多 20 个附件，单个不超过 50 MB；插入上传时编辑页短暂显示忙碌状态。撤销插入只撤销正文链接，已上传资源由 Joplin 的未引用附件清理规则处理。外部网络图片显示为可点击链接；已同步的 Joplin 图片直接显示。

阅读时单击内部链接或 draw.io 图片打开对应内容；富文本和即时编辑时使用 Ctrl+单击（macOS 为 Cmd+单击），普通单击用于编辑该段。其他位置同时修改正文时，编辑器保留本地输入并提示选择版本。

兼容 Admonition markdown extension 的 12 种提示框，例如：

!!! note 备注
Write details here
!!!
发布日期：2026-09-08

保留原始笔记内容，预览支持常见 Markdown 和安全的 HTML 样式。其他 Joplin 插件的自定义脚本不会在这里自动运行，需要分别适配其语法。

Mermaid 与 draw.io 图表

使用笔记预览上方或笔记右键菜单中的 插入 Mermaid，添加可直接修改的 Mermaid 代码块；正文和图形一起保存在笔记里。

使用 插入 draw.io 图，创建包含可编辑图形数据的 .drawio.svg 附件。安装或启用 Draw.io Integration（hediet.vscode-drawio） 后，可以点击预览中的图形，或选择 编辑 draw.io 图，直接打开图形编辑器。图形编辑器中的保存会写回原 Joplin 附件并刷新预览，附件 ID 和笔记链接保持不变。首次插入后也要保存笔记，才能同步新增的引用。

已有的 .drawio、.dio、.drawio.svg、.dio.svg、.drawio.png 和 .dio.png 文件可通过“插入图片或附件”加入并打开编辑。SVG/PNG 在笔记中显示图片，纯 .drawio/.dio 显示附件链接。普通 SVG/PNG 图片不一定含有 draw.io 的图形数据，不能直接转换成可编辑图形。

保存前会检查远端附件是否变化；冲突时保留本地编辑，请先将图形另存，再重新打开远端版本。编辑同一个附件会影响所有引用它的笔记。支持使用 VS Code 文件系统接口保存的图形扩展；本版本对接并验证 Draw.io Integration。

升级扩展后，请执行一次“开发人员: 重新加载窗口”，使新增视图和排序设置生效。如果窗口仍保留旧版注册信息，插件会显示明确提示并提供“重新加载窗口”按钮。

常用操作

笔记内部跳转

在笔记预览中直接点击内部链接即可打开目标笔记；源码模式使用 Ctrl+点击（macOS 为 Cmd+点击）。支持 [笔记名](:/笔记ID) 和 Joplin 的 joplin://x-callback-url/openNote?id=笔记ID 链接，均在 NoteBridge 内打开。

支持 [章节](:/笔记ID#章节标题)、[本页章节](#章节标题)，以及中文和 URL 编码的锚点。Markdown 标题按 Joplin 的规则生成锚点，重复标题依次添加 -2、-3；HTML 笔记使用原有标题 ID。已打开的笔记会复用，未保存内容会保留。目标需存在于当前连接；尚未同步或已删除的笔记会显示提示。

与聊天配合使用

在支持工具的 VS Code Chat 中，可以引用 #joplin_search_notes 搜索笔记、#joplin_read_note 读取内容，或通过 #joplin_save_summary 将总结保存为新笔记。新建、编辑、覆盖正文、移动和移入废纸篓，以及笔记本创建、重命名和移动，默认直接执行，不显示 NoteBridge 确认弹窗。可在设置中开启 joplinWorkbench.confirmWrites 恢复逐次确认，修改立即生效。旧设置 joplinWorkbench.confirmNoteCreation 仍可单独开启新建确认。AI 客户端自身的工具审批由客户端设置控制。

先设置默认保存目录，再保存编辑器选区或聊天总结。若要手动保存聊天回答，可将内容复制到编辑器，选中后保存。聊天功能及工具是否可用取决于当前 VS Code Chat 和模型配置。

在 Codex 和 Claude Code 中使用笔记

ChatGPT 和 Claude 桌面版可另外安装各自的 NoteBridge 独立包 2.0.0，直接连接 Joplin Desktop，无需安装或启动 VS Code，也不依赖本扩展。ChatGPT 需要支持本地 MCP 插件的模式；Claude Desktop 的 .mcpb 扩展与下面的 Claude Code 配置分别安装。

Copilot Chat 的拖拽附件使用笔记标题显示。Codex 和 Claude Code 通过 MCP 读取和记录笔记，不会自动继承 Copilot 的工具。

新打开的笔记标签页同样使用标题；已经打开的旧 ID 标签页可在保存后关闭并重新打开。同名笔记仍各自独立，笔记改名不会另开一份正在编辑的内容。

1. Codex：在每台电脑执行 Joplin: 为本机 Codex 配置 Joplin MCP，自动生成本机配置，无需另外安装 Node.js。 默认允许 Joplin 工具直接执行；已有的显式审批偏好和其他服务配置保持不变。
2. Claude Code：在每台电脑执行 Joplin: 为本机 Claude Code 配置 Joplin MCP，自动生成本机配置。
3. 重启 AI 扩展，再新建会话，并保持 NoteBridge 所在的 VS Code 窗口运行；桌面连接方式还需保持 Joplin 运行。
4. 右键笔记，选择 复制给 Codex / Claude 的笔记引用，粘贴到 AI 输入框，并提出你的要求。

也可以直接说“读取我当前打开的 Joplin 笔记”“把这份总结保存为默认笔记本中的新笔记”或“在某个笔记本中新建一篇记录”。AI 写入默认不弹窗，已有笔记先读取当前版本即可直接编辑、覆盖或删除。MCP 支持与内置 Chat 相同的 14 个笔记管理工具，另有 list_windows 选择窗口。可开启 joplinWorkbench.confirmWrites 恢复逐次确认。多个窗口无法唯一匹配时，AI 可通过 list_windows 选择目标。关闭“AI 接口”设置可停止连接。

Codex 和 Claude 的聊天面板不一定接受 VS Code 虚拟文件拖放；请使用上述引用入口。复制引用不会发送消息，也不会复制笔记正文。

使用提示

• HTML 笔记以源码形式编辑；保存时保留原格式。
• 笔记有未保存修改时，请先保存或取消修改，再执行其他管理操作。
• 如果提示内容冲突，请先保留自己的修改，再重新读取笔记并合并。
• 删除笔记本会包含其子笔记本和笔记；存在未保存修改时会停止。恢复时优先使用原目录，原目录不可用的笔记会要求选择新目录，笔记本则恢复到顶层。
• 标签删除只移除标签及关联，保留笔记；标签不进入废纸篓。
• 多项恢复、标签关联修改和多选操作逐项完成，失败或取消会显示已完成数量。
• 当前不提供笔记/笔记本永久删除功能。

English

Vortelyn NoteBridge for Joplin brings your notes into VS Code. Connect through the local desktop app or sign in to your self-hosted Joplin Server. Direct Server mode supports initialized sync format 3 accounts without E2EE; shared items are read-only and offline writes are not queued. Notes open in a ProseMirror rich text editor with a grouped formatting toolbar, heading outline, system/dark/light themes, and same-page live Markdown, reading and source views. Paste or drop images and files at the caret as native synchronized Joplin resources. Admonition, math, Mermaid, tables and other special blocks preserve their source and offer a source-edit button; table cells currently use source editing. Unchanged blocks retain their original Markdown.

Enable Web Clipper in Joplin, open the Joplin sidebar in VS Code, and connect using your authorization token. The default address is http://127.0.0.1:41184; keep Joplin running while using the extension. VS Code 1.130.0 or later is required.

Use the context menu to create top-level or nested notebooks, rename, move, edit note tags, copy links, or add items to chat. All Notes lists live notes across notebooks. Notebooks, notes and tags have separate persistent sort settings. Manage tags in the Tags view. Deleted notes and notebook subtrees appear in Trash, where notes can be viewed read-only and restored. Deleting a tag removes only the tag and its associations. Choose a default notebook before saving selections or summaries. Chat tools depend on your VS Code Chat setup. AI tools create, edit, replace, move and trash notes and manage notebooks without NoteBridge confirmation by default. Enable joplinWorkbench.confirmWrites to review every write. The legacy creation-only setting remains available. Client-side permission prompts are controlled by the AI client.

Copilot attachments display note titles. On each computer, run Joplin: Configure Joplin MCP for Codex on This Computer or Configure Joplin MCP for Claude Code on This Computer, then restart the AI extension and start a new conversation. Configuration uses the VS Code runtime, preserves other servers and settings, and backs up existing configuration. VS Code discovers Joplin MCP separately. Keep the NoteBridge window running. Use Copy note reference for Codex / Claude to specify a note, or ask the AI to read the current note, create a note or save a summary. All 14 Joplin tools are available over MCP. Writes execute directly by default; optional joplinWorkbench.confirmWrites restores review. Destination, connection, conflict and unsaved-editor checks remain active. Virtual-file drag support depends on the receiving extension; the copied reference works through MCP.

联系方式 / Contact

• 网站 / Website：vortelyn.cn
• 微信 / WeChat：vortelyn

在其他电脑连接 Codex

1. 安装 1.3.0 或更高版本，重新加载 VS Code，并连接本机 Joplin 或自建 Joplin Server。
2. 按 Ctrl+Shift+P，执行 Joplin: 为本机 Codex 配置 Joplin MCP；也可从笔记本视图的“…”菜单进入。
3. 在 Codex 设置中重启插件，再新建会话，查看 MCP 服务器列表中的 joplin。

每台电脑需要分别执行一次配置；仅安装扩展或同步 VS Code 设置不会自动配置 Codex。配置按当前电脑的路径生成，无需另外安装 Node.js；已有配置会备份，其他服务器与设置保留。默认配置位于 ~/.codex/config.toml，设置了 CODEX_HOME 时使用该目录。WSL 或远程 Codex 需要在对应环境配置。连接期间保持 NoteBridge 窗口运行。

Claude Code 使用 为本机 Claude Code 配置 Joplin MCP 命令，配置保存在 ~/.claude.json；设置 CLAUDE_CONFIG_DIR 后使用该目录下的 .claude.json。该用户级 MCP 配置供 Claude Code CLI 和 VS Code 扩展使用。