news 2026/9/10 1:28:11

思源笔记 v3.1.19 版本详解：超级块快捷键、本地文件系统同步、广播内核 API 与 20 项体验改进

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
思源笔记 v3.1.19 版本详解：超级块快捷键、本地文件系统同步、广播内核 API 与 20 项体验改进

思源笔记 v3.1.19 版本详解：超级块快捷键、本地文件系统同步、广播内核 API 与 20 项体验改进

【免费下载链接】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.1.19 的官方变更记录（见 app/changelogs/v3.1.x/v3.1.19/v3.1.19_zh_CN.md）为骨架，逐一解析该版本引入的 20 项功能改进、5 项缺陷修复与 2 项面向开发者的内核 API 新增。你将了解到：超级块布局切换快捷键如何配置、本地文件系统同步/备份的适用前提与底层实现、查询嵌入块导出转义等修复背后的代码逻辑，以及基于 WebSocket/SSE 的消息广播 API 如何用于插件与外部程序开发。文中所有结论均以当前仓库源码与配置为准，并给出可验证的文件路径。

版本概述与定位

v3.1.19 是思源笔记 v3.1.x 系列的一个细节改进版本，官方概述将其定位为"改进一些细节"。但从 变更记录 来看，该版本实际横跨了编辑器交互、数据库（属性视图）、云同步、搜索、剪藏、移动端与鸿蒙系统、内核 API等多个层面，且包含一个任意文件删除漏洞的安全修复，属于含金量较高的一次细节迭代。

根据本仓库 changelogs 目录结构（v3.1.x 系列），v3.1.19 处于 v3.1.18 与 v3.1.20 之间，可结合相邻版本记录对照查看演进脉络。

改进功能详解（20 项）

页签拖动与右键块选择

  • **改进页签拖动 中页签相关渲染与交互逻辑。
  • **改进右键块选择（行号槽/块标交互）与 app/src/protyle 其他块操作模块。

超级块：创建、布局切换与快捷键

超级块（Super Block）是思源笔记中用于将多个块组合成嵌套布局（水平/垂直）的容器块。本版本针对其做了两处改进：

  • **改进在超级块中创建新块 与 kernel/treenode 的节点操作逻辑中体现。
  • 添加取消超级块和切换到水平/垂直布局的快捷键：新增快捷键可在"取消超级块（拆分为普通块）"与"水平/垂直布局"之间快速切换。快捷键的注册与分发定义于 app/src/config/shortcuts.ts（config 模块），可在「设置 → 快捷键」中查看与自定义。

实操提示：若你的版本已包含此功能，可在快捷键设置中搜索"超级块"相关条目，将其绑定到顺手的手势；未绑定前请沿用块标菜单中的"布局"操作。

模板弹出窗口可调整预览区域大小

**模板弹出窗口支持拖动预览区域大小（模板渲染）与前端弹窗交互。

数据库（属性视图）改进

  • 数据库主键锚文本支持换行：数据库表中的主键字段（主键是文档的锚文本）现在支持多行显示，解决长标题折行问题。
  • 改进数据库关联和汇总样式：优化了数据库"关联"与"汇总"字段的展示样式。
  • 改进数据库资源字段弹出窗口：资源（附件/图片）字段的弹出预览窗口交互优化。

上述数据库能力对应内核中的 kernel/av 系列文件（属性视图/数据库核心逻辑），包括 kernel/av/av.go、kernel/av/layout.go 以及渲染侧 kernel/model/attribute_view_render.go。v3.1.19 的改动主要落在前端展示与交互层，内核数据结构保持稳定。

设置界面与搜索改进

  • **改进设置界面 提供的设置读写 API 与前端设置面板。
  • **改进搜索高亮 与 kernel/search（kernel/search/mark.go）中。
  • **改进搜索 OCR 图像预览区域定位 的 OCR 索引能力。

查找替换支持包含空格的关键字

**改进包含空格的关键字的查找替换 等文本处理模块。

移动端与平台适配

  • **在移动设备上编辑时禁用左右滑动弹出侧栏面板。
  • 在 Android 上申请相机权限时弹出用途说明：Android 端调用相机（如拍照插入）前会先说明权限用途，涉及移动端权限申请流程。
  • **改进对鸿蒙系统的支持。

云同步与本地文件系统同步/备份

支持本地文件系统同步和备份是本版本最具功能性的新增之一，下面重点展开。

同步 Provider 体系

思源笔记的同步引擎支持多种存储后端，在 kernel/conf/sync.go 中定义了 Provider 常量：

Provider值说明
ProviderSiYuan0思源官方云端存储服务
ProviderS32S3 协议对象存储
ProviderWebDAV3WebDAV 协议存储
ProviderLocal4本地文件系统存储

v3.1.19 的 PR #13663 正是为ProviderLocal补齐了同步与备份支持，即把"本地文件系统"作为与 WebDAV/S3 并列的同步目标目录（例如映射为网络盘、U 盘或本机其他目录），从而实现"本地备份 + 同步"。

同步主流程与实现位置

同步的核心入口位于 kernel/model/sync.go：

  • SyncDataJob()：定时同步任务（自动同步调度）；
  • SyncData(byHand bool)：手动或自动触发同步；
  • checkSync(boot, exit, byHand bool)：同步前置检查。

在 kernel/model/sync.go#L261-L274 的checkSync中可以看到，不同 Provider 的可用性校验逻辑不同：

switch Conf.Sync.Provider { case conf.ProviderSiYuan: if !IsSubscriber() { ... } case conf.ProviderWebDAV, conf.ProviderS3, conf.ProviderLocal: if !IsPaidUser() { ... } }

重要前提：从源码看，本地文件系统同步（ProviderLocal）与 WebDAV/S3 一样属于付费能力（IsPaidUser()校验），且需要先在「设置 → 同步」中开启同步并选择 Provider。

配置项

同步配置保存在 kernel/conf/sync.go 与 kernel/conf/conf.go 中。选择 WebDAV/S3 时，配置校验与规范化逻辑见 kernel/model/sync.go 的SetSyncProviderS3、SetSyncProvider等函数，以及 kernel/model/conf.go 中的默认值初始化（S3/WebDAV 默认启用SkipTlsVerify，端点经util.NormalizeEndpoint规范化）。

同时本版本还：

  • 移除 S3/WebDAV 云同步目录设置的「添加」和「移除」按钮：简化了云同步目录管理交互，目录配置改为更直接的编辑方式。此改动同样影响同步 Provider 配置界面。

同步目录（conf.Sync.CloudDir相关）用于指定工作空间数据在目标存储中的路径，参见 kernel/model/sync.go 的SetCloudSyncDir。

Windows Defender 排除项提示

**支持忽略添加 Microsoft Defender 排除项的提示 与 Windows 打包配置（electron-builder.yml）附近。

行级公式备注与微信剪藏

  • **改进在行级公式中添加备注 接入的 Lute 引擎。
  • **改进微信公众号文章剪藏。

修复缺陷详解（5 项）

Shift+Enter 软换行失效

**Shift+Enter在块内不执行软换行 的事务处理中生成，前端按键映射在 app/src/config/shortcuts.ts。

导出模板时正确转义查询嵌入块脚本

**导出模板时正确转义查询嵌入块脚本，嵌入块渲染见 kernel/model/embedding.go。

实操提示：导出/导入模板是跨工作区迁移"文档骨架 + 查询嵌入块"的常用手段，v3.1.19 后导出的模板在重新导入时脚本可保持原样。

任意文件删除漏洞（安全修复）

**任意文件删除漏洞、kernel/model/raw_path_guard.go 等文件操作路径对用户传入路径做了更严格的白名单/规范化校验。

升级建议：涉及本地文件操作的功能（如删除资源文件、清理未引用资源）与内核 HTTP API 直接相关，强烈建议所有自托管实例升级到 v3.1.19 或更高版本，尤其是暴露在局域网/公网的服务。

字体相关问题

  • **设置-编辑器-字体在 macOS 上显示乱码 与字体渲染（kernel/util/font.go）。
  • 加载某些字体文件导致内核崩溃：修复了加载畸形/特殊字体文件时内核崩溃（panic）的问题，属于健壮性修复，相关路径为 kernel/util/font.go 的字体解析与加载。

面向开发者的内核 API（2 项）

本版本面向插件与外部程序开发者新增了两项内核 API，均实现在 kernel/api/broadcast.go，属于同一套"广播消息"机制。

1. 发布二进制消息广播的内核 API（PR #13681）

内核新增了通过 HTTP 向广播频道推送二进制消息的 API：POST /api/broadcast/broadcastPublish。它基于 multipart/form-data 提交，一个表单字段名即一个频道名，支持向同一频道同时推送多条字符串与文件（二进制）消息。

请求与响应结构（见 kernel/api/broadcast.go 中broadcastPublish的注释定义）：

  • 请求：MultipartForm，字段名为频道名，值为字符串数组或文件列表；
  • 响应：data.results[]数组，每项包含：
    • code：0 表示成功，非 0（2/3/4/5）分别对应广播失败、文件打开失败、文件读取失败等；
    • channel：{name, count}，其中count为该频道当前订阅者数量；
    • message：{type, size, filename}，type为"string"或"binary"，字符串消息的filename为空字符串。

2. 通过 SSE 订阅广播消息的内核 API（PR #13694）

新增了基于SSE（Server-Sent Events）的订阅端点：GET /es/broadcast/subscribe。核心代码是broadcastSubscribe：

  • 通过retry查询参数指定重连间隔（毫秒，可选，见GetRetry）；
  • 通过可重复的channel查询参数订阅指定频道（Subscribe）；
  • 不传channel时订阅全部频道（SubscribeAll）。

示例（摘自源码注释 kernel/api/broadcast.go）：

http://localhost:6806/es/broadcast/subscribe?retry=1000&channel=test1&channel=test2
底层机制：双通道广播架构

这两项 API 共用一套"频道"抽象，理解其原理有助于插件开发：

  • 每个频道（BroadcastChannel，见 kernel/api/broadcast.go）同时维护：
    • 一个WebSocket 服务端（基于 melody 库，/ws/broadcast?channel=xxx），客户端可订阅并互发字符串/二进制消息；
    • 一个SSE 订阅者计数，用于统计统一 SSE 通道上的订阅数。
  • 全局单例UnifiedSSE基于 EventBus（事件名broadcast.message）把 WebSocket 与 SSE 两条链路统一：WebSocket 收到的消息会转投给 SSE 订阅者，反之BroadcastString/BroadcastBinary会同时写 WebSocket 会话并发送 SSE 事件。BroadcastChannel.SubscriberCount()汇总三类订阅者（WebSocket 会话数 + 频道 SSE 订阅数 + 全局 SSE 订阅数）。
  • 频道的创建（ConstructBroadcastChannel）、销毁（Destroy/DestroyBroadcastChannel）、清理（PruneBroadcastChannels）以及 WebSocket 最大消息大小（128 MiB）都在该文件中实现；WebSocket 端点注册于 kernel/api/router.go。

开发场景：这两项 API 组合可用于构建"内核 → 插件/外部程序"的推送通道，例如内核将二进制资源变更、自定义事件实时推送给多个订阅端；也可用于多端互联场景下的消息中转。

与既有推送体系的关系

值得注意的是，这套新增广播 API 与思源既有的 WebSocket 推送体系（kernel/util/websocket.go）并存：

  • 既有体系通过BroadcastByType、PushMsg、PushReloadDoc、PushProgress等函数，按会话类型（main/filetree/protyle等）向内核已连接的客户端广播 JSON 事件，用于界面刷新、状态栏消息、进度条等；
  • 新增广播 API 则是面向第三方订阅者的、按频道隔离的通用消息通道，二者在连接入口（/ws/broadcast与AddPushChan注册的/ws）、消息格式（二进制/SSE 事件 vs JSON Result）上相互独立。

快捷键速查与自定义

本版本涉及两处快捷键相关改动（超级块布局切换、Shift+Enter软换行修复）。思源的快捷键系统集中定义在 app/src/config/shortcuts.ts，在「设置 → 快捷键」界面可搜索并按需重绑定。常用相关快捷键示例：

功能默认快捷键（以实际设置为准）
插入软换行Shift+Enter
文档树/页签相关操作在快捷键设置中搜索"页签"

说明：上表仅列出变更记录明确涉及的键位；具体默认值与绑定情况请以「设置 → 快捷键」面板实际显示为准。

升级与获取

v3.1.19 的完整变更可对照 官方变更记录，相邻版本差异可查看 v3.1.x changelogs 目录。自托管部署方式见仓库根目录 Dockerfile 与 kernel/main.go 启动入口；若需源码级了解同步、广播 API 等实现，可重点阅读：

  • 同步引擎：kernel/model/sync.go、kernel/conf/sync.go
  • 广播 API：kernel/api/broadcast.go、kernel/util/websocket.go
  • 超级块/块操作：app/src/protyle/gutter/index.ts、kernel/treenode
  • 属性视图：kernel/av

小结

v3.1.19 作为一次"细节改进"版本，实际交付了超级块布局快捷键、本地文件系统同步/备份、模板预览拖动、数据库样式优化等实用功能，修复了包括任意文件删除漏洞在内的 5 个缺陷，并为开发者提供了WebSocket + SSE 双通道的二进制/字符串广播 API。无论你是日常使用者（关注同步、编辑体验与安全升级）还是插件开发者（关注广播 API），都可以在本文指引下结合对应源码文件深入验证与二次开发。

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

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

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/10 1:26:59

Unet系列分割模型对比实践：从Attention到R2U的科学训练

简介：面向计算机视觉与医学图像分析场景的深度学习资源包，提供Unet、AttentionUnet、R2Unet和R2AUet四种经典分割模型的可运行工程，并配有ISIC 2017皮肤病变数据集局部样本，零基础学习者可按照示例快速跑通，中高级研究…

作者头像 李华
网站建设 2026/9/10 1:26:57

c++ bug

报错： “D:\Build\gdal-3.10.2\INSTALL.vcxproj”(默认目标) (1) -> “D:\Build\gdal-3.10.2\ALL_BUILD.vcxproj”(默认目标) (3) -> “D:\Build\gdal-3.10.2\frmts\gif\gdal_GIF.vcxproj”(默认目标) (38) -> (ClCompile 目标) -> F:\Anaconda3\Librar…

作者头像 李华
网站建设 2026/9/10 1:23:22

GPT-6 Astra幻觉率2%却被老式SQL注入绕过？大模型安全防线为何失效

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华