Siyuan v3.6.5 版本解析：data-task 索引优化、Editor 细节改进与 Protyle 开发者 API 演进

本文基于 Siyuan 仓库中 v3.6.5 的官方变更记录（v3.6.5.md）展开，逐条解析该版本 14 项功能增强、11 项缺陷修复与 1 项运行时重构背后的技术含义，并结合当前仓库源码说明 data-task 任务标记、--b3-font-family-kbd 字体变量、openTab 与 switchMode 开发者 API 的实际实现位置，帮助读者理解这个“细节改进型”版本如何同时覆盖移动端体验、编辑器内核、数据索引与插件生态。

版本概述：一个以“细节打磨”为主线的版本

v3.6.5 的官方概述只有一句话：“This version improves some details.”（此版本改进了一些细节）。从 变更记录 的完整条目来看，这个版本的改动分布有明确的层次：

类别	数量	关注点
Enhancement（功能增强）	14	数据历史语义、移动端外观与工具栏、任务列表索引、快捷键、代码块行号性能、数据索引、输入法兼容、剪藏扩展
Bugfix（缺陷修复）	11	iOS 滚动跳转、IFrame 块、属性视图资源字段、大纲刷新、Cookie 超长认证、安全漏洞等
Refactor（重构）	1	升级 Electron 至 v40.9.1
Development（开发者 API）	3	独立窗口卸载插件修复、openTab 增加 doc.mode 参数、Protyle 实例新增 switchMode 方法

这类版本的价值在于：它把编辑器内核（data-task 索引、代码块行号渲染）、平台层（Electron 升级、移动端 WebView 行为）与插件 API 三条线的历史遗留问题集中收口。下面按主题逐组展开。

功能增强：逐条解析

数据历史：标签、书签与资源重命名记为 Replace 操作

将标签、书签和资源的重命名视为数据历史中的 Replace 操作（issue #17407）

SiYuan 的数据历史（data history）用于记录工作区中各类实体的变更轨迹。此前重命名一个标签、书签或资源（asset）可能产生“删除旧名 + 新增新名”两条记录，使历史噪音大且难以追溯。该版本将这类重命名统一语义化为单条 Replace 操作，历史回放与对比时能直接看出“旧名 → 新名”的对应关系，而不是两条孤立条目。对依赖数据历史做审计或回溯的用户来说，这是一次操作语义的修正。

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

改进任务列表项中 data-task 标记的 Markdown 索引（issue #17502）

这一条是 v3.6.5 中最有源码纵深的一项。SiYuan 的任务列表在 DOM 上通过 data-task 属性表达勾选状态，取值是 " "（未勾选）或 "X"（已勾选），并配合 data-marker、data-subtype="t" 等属性。在当前仓库中可以直接看到这套约定：

• wysiwyg/list.ts 中通过 taskItemElement.getAttribute("data-task") 读取状态，点击切换时在 " " 与 "X" 之间写入；新任务项的模板为 <div data-task=" " data-marker="*" data-subtype="t" ... class="li">...
• wysiwyg/turnIntoList.ts 在“转换为列表”时，用捕获到的 dataTask 值回填 data-task 属性（blockElement.parentElement.setAttribute("data-task", dataTask ? dataTask[1] : " ")），保证块类型转换后任务状态不丢失；
• util/editorCommonEvent.ts 在普通任务列表与任务项之间转换时，负责移除或补写 data-task 属性。

所谓“改进 data-task 标记的 Markdown 索引”，指的就是内核在把编辑器内容序列化为 Markdown（以及构建 FTS/属性索引）时，对携带 data-task 的任务项的处理更正确——勾选状态、列表标记（- [ ] / - [x]）能稳定地在“DOM ↔ Markdown ↔ 索引”三者间往返，而不会被 X/空值、换块、转换列表等操作破坏。这是搜索 - [x] 或按任务状态筛选结果准确性的底层保障。

移动端：行级文本外观设置与工具栏行为

两条移动端体验增强：

• 改进移动端行级文本（inline text）的外观设置（issue #17477）：移动端对选区行内样式的应用做了改进，使加粗、代码、高亮等行级文本样式在移动端的设置链路生效更完整；
• 移动端点击编辑器外部时工具栏不隐藏（issue #17478）：修正了移动端编辑器工具栏在点按编辑器外区域时误收起的问题，避免连续操作时工具栏反复出现的干扰。

标签快速切换与超链接锚文本解码

• 改进标签切换（issue #17505）：在标签面板中切换标签的交互路径做了简化，减少“选中标签 → 进入对应视图”的步骤成本；
• 改进粘贴超链接时对锚文本的解码（issue #17513）：粘贴带 URL 编码的超链接时，对锚文本（link text）做解码处理，避免把 %20 之类的编码残留直接粘贴进正文。

kbd 字体变量 --b3-font-family-kbd

改进 kbd 字体 --b3-font-family-kbd（issue #17517）

--b3-font-family-kbd 是 SiYuan 主题体系下控制 <kbd> 键帽渲染字体的 CSS 变量。在当前仓库中可以看到它的定义与消费点：

• 定义：内置主题 daylight/theme.css 与 midnight/theme.css 均将其映射为编辑器正文字体 --b3-font-family-protyle；
• 消费：component/_typography.scss 用 font: 75% var(--b3-font-family-kbd) 渲染 <kbd>，component/_menu.scss 用它渲染菜单快捷键提示，business/_config.scss、business/_search.scss 等处也有引用。

该版本对该变量的处理做了改进（默认取值/回退行为更合理），而主题作者依然可以通过在自定义主题的 CSS 中覆盖 --b3-font-family-kbd 来统一改变键帽字体，这是 SiYuan 主题定制的标准入口。

macOS 默认 Redo 快捷键调整为 ⇧⌘Z

将 macOS 上默认的重做快捷键改为 ⇧⌘Z（issue #17518）

这是对齐 macOS 平台肌肉记忆的调整：Cmd+Z 撤销、Shift+Cmd+Z 重做。改在默认快捷键配置层面，用户在“编辑 → 快捷键”中仍可覆盖。

表格撤销后的光标定位

改进表格中撤销后的光标定位（issue #17532）

表格是 SiYuan 编辑器中 DOM 结构最复杂的块之一，撤销（Undo）跨表格边界时容易出现光标“丢失”到文档头或表格外的情况。该版本针对 Undo 后选区/光标恢复逻辑做了表格场景专项修复，与下方“表格行号渲染”同属编辑器内核的稳定性打磨。

代码块行号渲染性能优化

优化代码块行号渲染以提升性能（issue #17542）

长代码块开启行号时，行号 gutter 的逐行 DOM 节点会带来可观的渲染开销。该版本对行号渲染路径做了优化（从源码结构看，属于 Protyle 渲染管线中 gutter 相关逻辑的重排/批量化改进），使大代码块的滚动与重渲染更平滑。

数据索引与输入法兼容性

• 改进数据索引（issue #17543）：索引构建链路的整体改进，与前述 data-task 索引修复、代码块性能优化共同构成这一版本对“索引—检索”链路的系统性打磨；
• 改进输入法兼容性（issue #17546）：针对中文/日文等 CJK 输入法组合（composition）状态下的边界问题（如组合中撤销、快捷键误触发）做兼容处理，这是富文本编辑器在 CJK 场景下的经典难点。

剪藏（Clipping）扩展：图片过大无法剪藏

改进剪藏扩展解决图片过大无法剪藏的问题（issue #17547）

网页剪藏在遇到超大图片时此前会直接失败，该版本对剪藏流程中的图片处理做了容错（压缩/降级处理），保证含大图的文章也能完成剪藏。

缺陷修复：按影响面分组

平台与窗口层

• iOS 点击编辑器导致页面跳到顶部（#17454）：修正移动端 WebView 中点按编辑器引发的整页滚动回顶问题，直接影响 iOS 端的日常编辑手感；
• 拆分标签页后出现空白区域（#17499）：多标签分屏布局的几何重算问题修复；
• 启动时缺少 window.siyuan.config 导致报错（#17508）：初始化时序问题——前端在注入的 window.siyuan.config 尚未就绪时访问它会产生错误，该版本对该启动路径做了防御；
• 修复一些安全漏洞（#17503）：官方未逐条披露细节，属于常规安全收口，建议所有自托管与桌面用户升级到该版本或更新版本。

编辑器内核

• IFrame 块无法编辑（#17486）：iframe 块此前丢失了编辑入口，恢复其可编辑性；
• 斜杠菜单中的 引用 选项无法搜索（#17510）：斜杠命令的模糊匹配对中文命令“引用”失效的修复，影响中文用户在斜杠菜单检索块类型的效率；
• 预览模式下大纲问题（#17551）与 大纲不会自动刷新（#17493）：两条均针对文档大纲面板——内容变更后大纲树未同步重建的问题，分别覆盖“编辑中自动刷新”与“预览模式”两种场景。

属性视图（AV）与云功能

• 将链接粘贴到数据库资源字段时创建重复条目（#17492）：数据库（属性视图）的资源（asset）字段在粘贴外链时会产生重复资源记录的写入逻辑修复；
• 云端配置界面中事件缺失（#17495）：订阅者“云配置”页面上部分事件类型未展示的问题。

认证与 Cookie

由于 Cookie 过长导致授权页验证失败（issue #17512）

认证态写入 Cookie 的长度超出浏览器/代理限制时，验证请求会整体失败。该版本对 Cookie 体积做了控制（例如精简/拆分 Cookie 内容），对多标签页、多工作区或带插件扩展了认证信息的场景更稳健。

运行时重构：升级到 Electron v40.9.1

升级到 Electron v40.9.1（issue #17501）

桌面端运行时是一次大版本跨度的升级（v40 系列），会带来 Chromium/Node 底层能力的同步更新。需要注意的是“以当前仓库实际内容为准”：当前仓库 app/package.json 中的 Electron 开发依赖已经进一步演进到 42.6.1，说明 v3.6.5 的这次升级只是 Siyuan 持续跟踪 Electron 主版本的节奏中的一步，桌面端用户实际获得的浏览器内核与 Node 能力以所安装版本自带的运行时为准。

开发者 API：插件与脚本可用到的三处变化

openTab 新增文档打开模式参数 doc.mode

为 openTab 添加文档打开模式参数 doc.mode（issue #17523）

openTab 是 SiYuan 暴露给插件的打开文档 API。此前插件打开一个块时，打开方式（当前标签、新标签、侧边栏等）由调用方间接决定；该版本在 openTab 的参数对象中显式引入 doc.mode 字段，让插件可以声明文档打开后的模式语义，与编辑器的编辑/预览模式控制打通。对插件作者而言，这是把“打开文档”与“以何种模式呈现”两步合二为一的 API 收敛。

Protyle 实例新增 switchMode 方法

为 Protyle 实例添加 switchMode 方法（issue #17552）

Protyle 是 SiYuan 的编辑器内核，插件与内置 UI 通过 app/src/protyle/index.ts 中的 Protyle 封装类与之交互。当前仓库中可以确认该方法的存在与实现：

// app/src/protyle/index.ts（第 597-599 行）
public switchMode(mode: TEditorMode) {
    setEditMode(this.protyle, mode);
}

即 switchMode(mode) 将目标编辑模式（编辑模式/预览模式等，类型 TEditorMode）委托给内核的 setEditMode 统一处理。插件开发者可以在运行时以编程方式切换某个 Protyle 实例的模式，而不必操纵 DOM 或依赖 UI 入口，配合上面 openTab 的 doc.mode，构成“打开即指定模式、打开后可切换模式”的完整控制链路。

独立窗口中卸载插件报错

独立窗口（standalone windows）中 uninstall 插件报错（issue #17509）

修复了插件独立窗口在卸载流程中的异常，属于插件生命周期管理在“独立窗口”这一特殊载体下的健壮性补洞。

如何在仓库中继续深入验证

阅读完本版本记录后，可以在当前仓库中沿以下路径核对实现细节（均以仓库根目录为起点）：

• 任务项 data-task 状态机：app/src/protyle/wysiwyg/list.ts、app/src/protyle/wysiwyg/turnIntoList.ts、app/src/protyle/util/editorCommonEvent.ts；
• switchMode 开发者 API：app/src/protyle/index.ts；
• --b3-font-family-kbd 主题变量定义：app/appearance/themes/daylight/theme.css、app/appearance/themes/midnight/theme.css；
• 桌面端运行时依赖：app/package.json；
• 本版本原始变更记录（英文/简中/繁中）：v3.6.5.md、v3.6.5_zh_CN.md、v3.6.5_zh_CHT.md。

小结与升级建议

v3.6.5 没有引入大型新功能，但它把“任务列表状态在索引链路中的正确性（data-task）”“移动端编辑体验（滚动、工具栏、行内样式）”“编辑器内核稳定性（表格撤销、IFrame 块、大纲刷新）”“桌面运行时（Electron v40.9.1）”与“插件 API（doc.mode、switchMode）”五件事一次做完。对使用者，最直接的收益是 iOS 端不再跳顶、标签/书签/资源重命名在数据历史中语义清晰、安全漏洞得到修复；对插件开发者，openTab 的 doc.mode 参数与 Protyle switchMode 方法让“模式控制”第一次成为可编程的一等能力。如果你仍在 v3.6.4 或更早版本，升级到 v3.6.5 及后续版本是低风险且收益明确的（其中包含安全修复，建议尽快跟进）。