思源笔记 v3.6.5 更新日志深度解析：细节改进、缺陷修复与插件 API 增强-开发者社区

思源笔记 v3.6.5 更新日志深度解析：细节改进、缺陷修复与插件 API 增强

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan

本篇技术指南围绕思源笔记（SiYuan）v3.6.5 版本的官方更新日志展开，逐一解读该版本在数据历史、移动端交互、Markdown 索引、编辑体验、输入法兼容性等方面的改进项与缺陷修复，并结合当前仓库（app/前端与kernel/后端源码）揭示每项变更背后的实现原理。读完本文，你将清楚了解 v3.6.5 中"将标签/书签/资源重命名视为Replace历史操作"的数据层机制、任务列表data-task标记的索引约束、openTab新增的doc.mode参数用法，以及 Protyle 实例新增的switchMode方法等开发者能力。

版本概述

v3.6.5 是思源笔记 3.6.x 系列的一次细节打磨型版本，官方更新日志（v3.6.5_zh_CN.md）给出的概述为"此版本改进了一些细节"。变更记录共分为四类：

改进功能：13 项，覆盖数据历史、移动端交互、编辑体验、索引与渲染性能等；
修复缺陷：11 项，覆盖 iOS、IFrame、数据库资源字段、大纲、安全漏洞等；
开发重构：1 项，升级 Electron 至 v40.9.1；
开发者：3 项，涉及插件卸载、openTab新参数与 Protyle 新方法。

改进功能详解

1. 标签、书签和资源的重命名统一记入数据历史（`Replace`操作）

此前，标签、书签和资源的重命名在数据历史中的记录方式与普通文档变更不一致。v3.6.5 将这三类重命名统一视为Replace（替换）操作写入数据历史，使历史回溯行为更可预期。

从源码看，数据历史的操作类型常量定义于 kernel/model/history.go：

const ( HistoryOpClean = "clean" HistoryOpUpdate = "update" HistoryOpDelete = "delete" HistoryOpFormat = "format" HistoryOpSync = "sync" HistoryOpReplace = "replace" HistoryOpOutline = "outline" )

HistoryOpReplace在 v3.6.5 中正是被用于标签、书签和资源这三类重命名场景，仓库中的调用点可以印证这一设计：

标签重命名/删除：kernel/model/tag.go 与 kernel/model/tag.go 在生成历史时调用getHistoryDir(HistoryOpReplace)；
书签操作：kernel/model/bookmark.go 与 kernel/model/bookmark.go；
资源操作：kernel/model/assets.go；
搜索相关数据：kernel/model/search.go。

以标签为例，kernel/model/tag.go 中RemoveTag的执行流程是：先通过sql.QueryTagSpansByLabel(label)查询所有包含该标签的块，再按RootID分组，随后为每个受影响的树调用generateTreeHistory(tree, historyDir)生成replace类型的历史快照，最后才批量修改节点并重建索引。也就是说，任何重命名操作发生前，都会先在data/history/replace目录留下完整的树快照，保证用户可以随时回滚。

2. 任务列表项`data-task`标记的 Markdown 索引改进

思源笔记的任务列表项通过data-task属性标记当前状态（如[x]已完成、[ ]未完成以及自定义状态）。v3.6.5 改进了该标记在 Markdown 索引中的解析行为，使自定义任务状态的索引更准确。

后端对data-task有明确的保护性约束，见 kernel/model/blockial.go：

if lowerName == "data-task" { err = errors.New(`setting or removing [data-task] attribute is not allowed via this interface. Please use "/api/block/updateTaskListItemMarker" or "/api/block/batchUpdateTaskListItemMarker" to update the task list item marker`) }

即data-task属性不允许通过通用的属性设置接口（IAL 更新）直接修改，必须走专用的任务标记 API。这两个专用 API 实现于 kernel/api/block_op.go，其核心校验逻辑在 kernel/api/block_op.go：

标记长度必须为 1 个字符（task list item marker length should be 1）；
不允许使用[或]（避免与 Markdown 任务语法冲突）；
通过 Lute 解析器定位ast.NodeTaskListItemMarker节点后写入新标记，并同步更新TaskListItemChecked状态。

v3.6.5 对data-task的 Markdown 索引改进，正是为了确保这些自定义状态在搜索、反链、数据索引等场景下能保持一致性与正确性。

3. 移动端交互与外观改进

本版本对移动端进行了三项针对性优化：

改进行级文本的外观设置：移动端对行级文本（如加粗、斜体、行内代码等）的样式设置入口与展示效果得到优化；
点击编辑器外部时工具栏不再隐藏：此前移动端点击编辑器外部区域会误收起工具栏，v3.6.5 修复了该交互逻辑，使工具栏的显隐行为更符合用户预期；
改进标签切换：移动端在编辑器与文档之间切换标签页时更加顺畅。

4. 编辑体验改进

粘贴超链接时对锚文本的解码：当复制的链接包含 URL 编码的锚文本时，粘贴后会正确解码，避免出现乱码或错误文本；
改进kbd字体--b3-font-family-kbd：对键盘按键样式（<kbd>元素）的字体系列变量进行了调整。该 CSS 变量在前端样式系统中被广泛引用，例如 app/src/assets/scss/business/_config.scss、app/src/assets/scss/business/_search.scss、app/src/assets/scss/component/_menu.scss、app/src/assets/scss/component/_typography.scss 与 app/src/assets/scss/util/_function.scss 均通过font: 75% var(--b3-font-family-kbd)之类的声明引用该变量。用户可在外观主题中自定义--b3-font-family-kbd以覆盖默认的等宽字体；
将 macOS 上默认的重做快捷键改为⇧⌘Z：这是 macOS 平台的系统惯例（Cmd+Shift+Z），此前与思源默认的重做快捷键存在差异，本版本统一对齐；
改进表格中撤销后的光标定位：在表格中执行撤销操作后，光标能够恢复到正确的单元格位置；
优化代码块行号渲染以提升性能：代码块行号在长文档中的渲染开销被优化，滚动与编辑时的卡顿感降低。

5. 数据索引与兼容性改进

改进数据索引：对数据仓库（data repo）的索引流程进行了修正，提升索引一致性；
改进输入法兼容性：优化了中文等输入法组合输入过程中的光标与文本状态同步问题；
改进剪藏扩展解决图片过大无法剪藏：浏览器剪藏扩展在遇到超大图片时不再因体积限制而失败。

修复缺陷详解

v3.6.5 共修复 11 个缺陷，覆盖平台兼容、编辑器核心与安全三类：

平台与安全

iOS 上点击编辑器可能导致页面跳到顶部：修复了 iOS 端点击编辑区时因焦点处理导致的滚动位置丢失问题；
启动时缺少window.siyuan.config会导致报错：修复了某些环境下前端启动时序问题——window.siyuan.config尚未注入时即被访问所引发的异常；
由于 Cookie 过长导致授权页验证失败：修复了云端/认证场景中 Cookie 超过浏览器上限导致授权流程失败的缺陷；
修复一些安全漏洞：本版本包含安全修补，建议用户尽快升级。

编辑器与界面

IFrame 块无法编辑：修复了嵌入网页（IFrame）块在编辑状态下无法操作的问题；
将链接粘贴到数据库资源字段时会创建重复条目：修复了向数据库（属性视图）资源字段粘贴链接导致重复记录的缺陷；
大纲不会自动刷新：修复了文档内容变化后大纲面板不同步更新的问题；
拆分标签页后出现空白区域：修复了布局中拆分标签页产生的空白残留；
斜杠菜单中的引用选项无法搜索：修复了斜杠菜单内"引用"条目在关键字过滤时无法命中的问题；
修复预览模式下大纲的问题：修复了阅读（预览）模式下大纲面板的显示与定位异常。

开发重构：Electron 升级至 v40.9.1

v3.6.5 将桌面端底层框架 Electron 升级到 v40.9.1，跟随上游修复了渲染进程与系统集成层面的若干问题。Electron 版本在 app/package.json 中声明（当前仓库主分支的electron依赖版本已进一步演进），桌面端打包配置见仓库根目录下的 electron-builder.yml 及各平台变体（如 electron-builder-darwin.yml、electron-builder-linux.yml）。

开发者相关变更

独立窗口中卸载插件报错修复

此前在独立窗口中执行插件卸载会因窗口上下文不一致而报错，v3.6.5 修复了该问题，确保插件管理器在独立窗口场景下可以正常卸载插件。

为`openTab`添加文档打开模式参数`doc.mode`

插件 APIopenTab的文档打开选项新增了mode参数，允许开发者控制新打开的文档以"所见即所得"还是"预览"模式呈现。TEditorMode类型的定义位于 app/src/types/protyle.d.ts：

type TEditorMode = "preview" | "wysiwyg"

在 app/src/plugin/API.ts 中，doc.mode被透传给底层打开文档的函数：

return openFileById({ app: options.app, keepCursor: options.keepCursor, removeCurrentTab: options.removeCurrentTab, position: options.position, afterOpen: options.afterOpen, id: options.doc.id, action: options.doc.action, zoomIn: options.doc.zoomIn, scrollPosition: "start", mode: options.doc.mode, });

而 app/src/editor/util.ts 中openFileById的签名明确声明了可选参数mode?: TEditorMode，并在内部通过openFile将其传递给编辑器模型初始化。开发者可通过如下方式让文档以预览模式打开：

siyuan.openTab({ app: this.app, doc: { id: "20210808180117-6v0mkxr", mode: "preview", // 或 "wysiwyg" }, });

为 Protyle 实例添加`switchMode`方法

Protyle（思源内核编辑器）实例新增了switchMode(mode)方法，用于在preview（预览）与wysiwyg（所见即所得）两种编辑模式间切换。实现位于 app/src/protyle/index.ts：

public switchMode(mode: TEditorMode) { setEditMode(this.protyle, mode); }

底层逻辑在 app/src/protyle/util/setEditMode.ts 中实现：切换到preview时会隐藏编辑内容元素与滚动条、渲染预览内容并更新大纲；切换到wysiwyg时会隐藏预览层、恢复编辑层并触发resize重排。该方法同样被面包屑（breadcrumb）组件用于切换编辑/预览状态（见 app/src/protyle/breadcrumb/index.ts）。

如何获取 v3.6.5

该版本作为思源笔记 3.6.x 系列更新发布，用户可通过思源官网下载页或 GitHub Releases 获取对应平台的安装包。桌面端支持 Windows、macOS 与 Linux，各平台构建配置可参考仓库中的 electron-builder.yml 及其平台变体。v3.6.5 的完整变更记录可在仓库 app/changelogs/v3.6.x/v3.6.5/ 目录下查看，该目录同时提供英文（v3.6.5.md）、简体中文（v3.6.5.zh-CN.md）与繁体中文（v3.6.5.zh-TW.md）三个版本。

小结

v3.6.5 虽然定位为"细节改进"版本，但其变更横跨数据历史模型（Replace操作类型）、任务标记约束（data-taskAPI 收紧）、编辑器交互与渲染性能、Electron 底座升级以及插件 API 扩展（doc.mode与switchMode）等多个层面。对于插件开发者而言，openTab的doc.mode与 Protyle 的switchMode提供了更精细的文档打开与模式控制能力；对于普通用户，输入法兼容性、粘贴解码、iOS 滚动、大纲刷新等修复则直接提升了日常编辑体验。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

思源笔记 v3.6.5 更新日志深度解析：细节改进、缺陷修复与插件 API 增强