思源笔记 v3.4.1 更新深度解析OCR 超时控制、Eventbus 排序事件与移动端体验改进【免费下载链接】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.4.1 简体中文变更日志系统解读该版本的 16 项功能改进、1 项缺陷修复与 1 项开发者能力增强。文章结合 kernel/util/ocr.go、kernel/model/file.go、kernel/model/box.go 等源码实现深入剖析SIYUAN_TESSERACT_TIMEOUT环境变量的工作原理、Eventbus 新事件的触发链路等底层机制。读者读完将完整掌握 v3.4.1 的版本增量、关键配置方法与可复用的插件开发接口。版本概述一次全面而克制的细节打磨v3.4.1 的官方描述是此版本改进了一些细节但从变更清单看这是一次覆盖面很广的稳定性与体验优化版本既有面向所有平台的编辑器、渲染、搜索、数据库交互改进也有专门针对 iOS、Android 移动端的系统级能力补齐同时包含剪藏、图片 OCR、数据索引等基础设施层面的增强并修复了一处可能导致内核启动崩溃的 S3 同步缺陷。与上一版本相比该版本没有引入破坏性变更核心变化集中在细节体验与稳定性两个维度适合所有用户无痛升级。改进功能详解数据库复制副本行为与操作交互优化数据库绑定的块在被复制为副本后不再自动添加到数据库此前将数据库中绑定的块复制为副本时副本会自动进入数据库容易造成数据条目冗余v3.4.1 改变了这一行为复制出的副本不再自动入库用户需要手动决定是否将其加入数据库避免了误操作带来的数据污染。改进数据库操作交互对数据库的日常操作流程进行了交互层优化使行列管理、字段编辑等操作更加顺手。编辑器与渲染从 iframe 到光标的细节打磨改进 iframe/挂件Widget的渲染针对 iframe 与挂件在文档中的渲染表现进行优化减少了嵌入内容加载时的布局抖动与显示异常。在块开头的零宽空格ZWSP处改进左右箭头键的行为当光标位于块首的零宽空格字符处时左右箭头键的移动逻辑得到修正避免光标被困在不可见字符上提升了行首行尾导航的精确性。搜索结果定位与检索条件优化打开搜索结果时将块居中并高亮从搜索结果点击跳转时目标块会在编辑区自动居中并高亮显示帮助用户在长文档中快速定位命中内容这一改进同时改善了阅读与审校场景下的上下文感知。快捷搜索不包含键位条件此前快捷搜索会自动携带某些键位过滤条件导致结果意外受限v3.4.1 移除了该隐式条件使快捷搜索默认返回更完整的结果集。移动端系统打印与退出流程完善支持在 iOS 上调用系统打印iOS 端现在可以直接调用系统原生打印能力将文档内容输出到支持 AirPrint 的打印机移动端办公与资料归档更加便捷。改进移动端打印除 iOS 外其他移动端环境的打印流程也一并优化打印输出的格式与稳定性得到提升。改进 Android 上的退出修正了 Android 端退出应用时的流程减少后台残留与资源未释放的问题。剪藏与 OCR更广的格式覆盖与可配置超时改进 HTML SVG 剪藏网页剪藏对 SVG 图形的处理得到增强剪藏后的 SVG 能更完整地保留在笔记中。图片 OCR 支持更多格式OCR 可识别的图片格式范围扩大。查看 kernel/util/ocr.go 中的tesseractExts列表可知v3.4.1 及后续版本支持的格式包括.png、.jpg、.jpeg、.tif、.tiff、.bmp、.gif、.webp、.pbm、.pgm、.ppm、.pnm共 12 种其中.pbm、.pgm、.ppm、.pnm等便携位图格式为本次扩展的重点覆盖了更多扫描仪与图像处理工具的输出。图片 OCR 支持通过环境变量SIYUAN_TESSERACT_TIMEOUT设置超时这是本版本最值得关注的工程化改进之一下文单独展开。界面与索引加载速度与定位体验切换主题和更新代码片段后改进界面加载优化了主题切换与代码片段Snippet更新后的界面重载流程减少样式闪烁与白屏等待。改进大纲定位大纲面板点击跳转的定位准确性得到修正长文档中大纲 → 正文的导航体验更可靠。改进数据索引性能对数据索引数据库索引构建流程做了性能优化在大型工作空间下可感知到索引构建与更新速度的提升。浏览器剪藏复制上下文菜单新增复制网页 URL在浏览器的复制上下文菜单中添加复制网页 URL在浏览器中选中文本进行复制时思源提供的复制菜单新增了复制网页 URL选项便于在剪藏时同时保留来源地址方便溯源。该功能由社区 PR 贡献见变更日志中的 pull request 记录。缺陷修复S3 同步导致的内核启动崩溃使用 S3 数据同步可能导致内核启动时崩溃当用户配置了 S3 作为数据同步目标时在某些状态下内核Kernel启动阶段可能发生崩溃。v3.4.1 修复了该问题保障了 S3 同步场景下应用启动的稳定性。对使用 S3 同步的用户本版本属于强烈建议升级的修复性版本。开发者能力Eventbus 新增两个排序事件v3.4.1 向内核 Eventbus 新增了两个事件filetreeSortChanged与notebookSortChanged。这两个事件是文件树Filetree与笔记本Notebook排序变化时向外部主要是插件广播的信号为插件开发者提供了观察与响应文档结构排序变化的能力。事件触发链路从排序操作到前端广播notebookSortChanged的触发点位于 kernel/model/box.go 的ChangeBoxSort函数约 L907-L922。当用户调整笔记本排序时内核会遍历传入的boxIDs将每个笔记本的boxConf.Sort依次写为i 1并保存配置随后通过util.BroadcastByType(main, notebookSortChanged, 0, , ...)广播事件携带的数据为最新的notebookIDs列表func ChangeBoxSort(boxIDs []string) { for i, boxID : range boxIDs { box : Box{ID: boxID} boxConf : box.GetConf() boxConf.Sort i 1 box.SaveConf(boxConf) } // ... util.BroadcastByType(main, notebookSortChanged, 0, , map[string]any{ notebookIDs: notebookIDs, }) }filetreeSortChanged的触发点位于 kernel/model/file.go 的pushFiletreeSortChanged函数约 L2261-L2285。该函数由文件树排序写入流程调用排序结果先写入笔记本下的.siyuan/sort.json配置文件writeSortConfMap随后将受影响的子文档 ID 按新顺序排序取第一个子文档的父路径作为parentPath连同childIDs一起广播func pushFiletreeSortChanged(sortIDs map[string]int) { // 将 sortIDs 按值升序排列得到 childIDs ... firstID : childIDs[0] bt : treenode.GetBlockTree(firstID) // ... util.BroadcastByType(main, filetreeSortChanged, 0, , map[string]any{ parentPath: parentPath, childIDs: childIDs, }) }广播机制的底层实现两个事件最终都走util.BroadcastByType其实现位于 kernel/util/websocket.go约 L86-L97。该函数通过SessionsByType(typ)收集所有type为main的 WebSocket 会话基于 melody 库的 session 管理并向每个会话写入一条携带cmd即事件名与data的事件消息func BroadcastByType(typ, cmd string, code int, msg string, data any) { typeSessions : SessionsByType(typ) for _, sess : range typeSessions { event : NewResult() event.Cmd cmd event.Code code event.Msg msg event.Data data sess.Write(event.Bytes()) } }这意味着插件可以通过思源的 WebSocket 事件通道订阅filetreeSortChanged/notebookSortChanged在用户拖拽排序文件树或笔记本后即时感知变化进而实现排序状态同步到自定义视图或按排序批量处理文档等联动功能。这两个事件在插件生态中可作为观察文档组织结构的标准化信号使用。源码深挖SIYUAN_TESSERACT_TIMEOUT超时机制的完整实现图片 OCR 的超时控制是 v3.4.1 中可配置性最强的一项变更值得从源码层面完整理解。相关逻辑集中在 kernel/util/ocr.go 的Tesseract函数约 L246-L269timeout : 7000 timeoutEnv : os.Getenv(SIYUAN_TESSERACT_TIMEOUT) if ! timeoutEnv { if timeoutParsed, parseErr : strconv.Atoi(timeoutEnv); nil parseErr { timeout timeoutParsed } else { logging.LogWarnf(parse tesseract timeout [%s] failed: %s, timeoutEnv, parseErr) } } ctx, cancel : context.WithTimeout(context.Background(), time.Duration(timeout)*time.Millisecond) defer cancel()实现要点如下默认值 7000未设置环境变量时OCR 超时默认为 7000 毫秒7 秒与旧版本行为保持一致升级无感知。单位是毫秒环境变量的数值按毫秒解析设置SIYUAN_TESSERACT_TIMEOUT10000即表示 10 秒。非法值安全回退若环境变量无法被strconv.Atoi解析为整数内核不会崩溃而是记录一条parse tesseract timeout [...] failed的警告日志并继续使用默认 7000ms。超时通过context.WithTimeout生效OCR 子进程以exec.CommandContext启动超时到达后ctx.Err()返回context.DeadlineExceeded内核会记录tesseract [...] timeout [7000ms]警告日志并放弃本次识别避免 tesseract 进程长时间占用资源。配套的稳定性设计Tesseract函数内部还使用全局互斥锁tesseractOCRLock将 OCR 串行化执行注释明确说明这是为提升稳定性而引入对应 issue #7265同时对图片大小做了限制——超过TesseractMaxSize2 MB的图片会直接跳过识别。这些约束配合可配置超时共同保障了 OCR 在低性能设备与超大图片场景下的健壮性。实际调用的 tesseract 命令行位于同函数下方约 L258tesseract -c debug_file/dev/null 图片绝对路径 stdout -l 语言列表以连接 tsv即使用-l指定识别语言多个语言用连接如chi_simeng并以 TSV 格式输出到 stdout内核随后解析 TSV 数据生成带坐标的 OCR 文本块。此外 OCR 功能默认仅在标准容器ContainerStd环境下启用且受TesseractEnabled开关控制启用状态与最大文件大小等参数在 kernel/util/ocr.go 中初始化并记录日志tesseract-ocr enabled [ver..., maxSize..., langs...]。使用建议在部署或自托管思源内核时若你的工作空间包含大量高分辨率截图且设备性能有限可通过环境变量调整 OCR 超时# 将 OCR 超时调整为 15 秒默认 7000ms SIYUAN_TESSERACT_TIMEOUT15000 ./kernel若 OCR 频繁超时且大量图片识别失败建议优先排查图片体积超过 2 MB 的图片本就不会被识别与 tesseract 语言包是否完整安装再考虑适当调大超时值。版本信息与下载v3.4.1 变更日志同时提供英文v3.4.1.md、简体中文v3.4.1_zh_CN.md与繁体中文v3.4.1_zh_CHT.md三个版本便于不同语言用户对照查阅。安装包可通过思源官方下载页获取完整的历史变更记录可参阅仓库根目录的 CHANGELOG.md 及 app/changelogs 目录下的各版本日志。小结v3.4.1 是一个典型的细节密集型维护版本数据库复制语义的修正、搜索定位的高亮居中、移动端系统打印与退出流程的补齐体现了对高频操作体验的持续投入S3 同步崩溃的修复则具有明确的稳定性价值而SIYUAN_TESSERACT_TIMEOUT环境变量与 Eventbus 新事件为运维人员与插件开发者分别提供了可配置性与可观测性上的增量。对于开发者而言通过filetreeSortChanged/notebookSortChanged事件订阅文档结构变化结合 kernel/util/websocket.go 中的 WebSocket 广播机制可以构建出与思源文件树深度联动的第三方能力。【免费下载链接】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），仅供参考 思源笔记 v3.4.1 更新深度解析：OCR 超时控制、Eventbus 排序事件与移动端体验改进
思源笔记 v3.4.1 更新深度解析OCR 超时控制、Eventbus 排序事件与移动端体验改进【免费下载链接】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.4.1 简体中文变更日志系统解读该版本的 16 项功能改进、1 项缺陷修复与 1 项开发者能力增强。文章结合 kernel/util/ocr.go、kernel/model/file.go、kernel/model/box.go 等源码实现深入剖析SIYUAN_TESSERACT_TIMEOUT环境变量的工作原理、Eventbus 新事件的触发链路等底层机制。读者读完将完整掌握 v3.4.1 的版本增量、关键配置方法与可复用的插件开发接口。版本概述一次全面而克制的细节打磨v3.4.1 的官方描述是此版本改进了一些细节但从变更清单看这是一次覆盖面很广的稳定性与体验优化版本既有面向所有平台的编辑器、渲染、搜索、数据库交互改进也有专门针对 iOS、Android 移动端的系统级能力补齐同时包含剪藏、图片 OCR、数据索引等基础设施层面的增强并修复了一处可能导致内核启动崩溃的 S3 同步缺陷。与上一版本相比该版本没有引入破坏性变更核心变化集中在细节体验与稳定性两个维度适合所有用户无痛升级。改进功能详解数据库复制副本行为与操作交互优化数据库绑定的块在被复制为副本后不再自动添加到数据库此前将数据库中绑定的块复制为副本时副本会自动进入数据库容易造成数据条目冗余v3.4.1 改变了这一行为复制出的副本不再自动入库用户需要手动决定是否将其加入数据库避免了误操作带来的数据污染。改进数据库操作交互对数据库的日常操作流程进行了交互层优化使行列管理、字段编辑等操作更加顺手。编辑器与渲染从 iframe 到光标的细节打磨改进 iframe/挂件Widget的渲染针对 iframe 与挂件在文档中的渲染表现进行优化减少了嵌入内容加载时的布局抖动与显示异常。在块开头的零宽空格ZWSP处改进左右箭头键的行为当光标位于块首的零宽空格字符处时左右箭头键的移动逻辑得到修正避免光标被困在不可见字符上提升了行首行尾导航的精确性。搜索结果定位与检索条件优化打开搜索结果时将块居中并高亮从搜索结果点击跳转时目标块会在编辑区自动居中并高亮显示帮助用户在长文档中快速定位命中内容这一改进同时改善了阅读与审校场景下的上下文感知。快捷搜索不包含键位条件此前快捷搜索会自动携带某些键位过滤条件导致结果意外受限v3.4.1 移除了该隐式条件使快捷搜索默认返回更完整的结果集。移动端系统打印与退出流程完善支持在 iOS 上调用系统打印iOS 端现在可以直接调用系统原生打印能力将文档内容输出到支持 AirPrint 的打印机移动端办公与资料归档更加便捷。改进移动端打印除 iOS 外其他移动端环境的打印流程也一并优化打印输出的格式与稳定性得到提升。改进 Android 上的退出修正了 Android 端退出应用时的流程减少后台残留与资源未释放的问题。剪藏与 OCR更广的格式覆盖与可配置超时改进 HTML SVG 剪藏网页剪藏对 SVG 图形的处理得到增强剪藏后的 SVG 能更完整地保留在笔记中。图片 OCR 支持更多格式OCR 可识别的图片格式范围扩大。查看 kernel/util/ocr.go 中的tesseractExts列表可知v3.4.1 及后续版本支持的格式包括.png、.jpg、.jpeg、.tif、.tiff、.bmp、.gif、.webp、.pbm、.pgm、.ppm、.pnm共 12 种其中.pbm、.pgm、.ppm、.pnm等便携位图格式为本次扩展的重点覆盖了更多扫描仪与图像处理工具的输出。图片 OCR 支持通过环境变量SIYUAN_TESSERACT_TIMEOUT设置超时这是本版本最值得关注的工程化改进之一下文单独展开。界面与索引加载速度与定位体验切换主题和更新代码片段后改进界面加载优化了主题切换与代码片段Snippet更新后的界面重载流程减少样式闪烁与白屏等待。改进大纲定位大纲面板点击跳转的定位准确性得到修正长文档中大纲 → 正文的导航体验更可靠。改进数据索引性能对数据索引数据库索引构建流程做了性能优化在大型工作空间下可感知到索引构建与更新速度的提升。浏览器剪藏复制上下文菜单新增复制网页 URL在浏览器的复制上下文菜单中添加复制网页 URL在浏览器中选中文本进行复制时思源提供的复制菜单新增了复制网页 URL选项便于在剪藏时同时保留来源地址方便溯源。该功能由社区 PR 贡献见变更日志中的 pull request 记录。缺陷修复S3 同步导致的内核启动崩溃使用 S3 数据同步可能导致内核启动时崩溃当用户配置了 S3 作为数据同步目标时在某些状态下内核Kernel启动阶段可能发生崩溃。v3.4.1 修复了该问题保障了 S3 同步场景下应用启动的稳定性。对使用 S3 同步的用户本版本属于强烈建议升级的修复性版本。开发者能力Eventbus 新增两个排序事件v3.4.1 向内核 Eventbus 新增了两个事件filetreeSortChanged与notebookSortChanged。这两个事件是文件树Filetree与笔记本Notebook排序变化时向外部主要是插件广播的信号为插件开发者提供了观察与响应文档结构排序变化的能力。事件触发链路从排序操作到前端广播notebookSortChanged的触发点位于 kernel/model/box.go 的ChangeBoxSort函数约 L907-L922。当用户调整笔记本排序时内核会遍历传入的boxIDs将每个笔记本的boxConf.Sort依次写为i 1并保存配置随后通过util.BroadcastByType(main, notebookSortChanged, 0, , ...)广播事件携带的数据为最新的notebookIDs列表func ChangeBoxSort(boxIDs []string) { for i, boxID : range boxIDs { box : Box{ID: boxID} boxConf : box.GetConf() boxConf.Sort i 1 box.SaveConf(boxConf) } // ... util.BroadcastByType(main, notebookSortChanged, 0, , map[string]any{ notebookIDs: notebookIDs, }) }filetreeSortChanged的触发点位于 kernel/model/file.go 的pushFiletreeSortChanged函数约 L2261-L2285。该函数由文件树排序写入流程调用排序结果先写入笔记本下的.siyuan/sort.json配置文件writeSortConfMap随后将受影响的子文档 ID 按新顺序排序取第一个子文档的父路径作为parentPath连同childIDs一起广播func pushFiletreeSortChanged(sortIDs map[string]int) { // 将 sortIDs 按值升序排列得到 childIDs ... firstID : childIDs[0] bt : treenode.GetBlockTree(firstID) // ... util.BroadcastByType(main, filetreeSortChanged, 0, , map[string]any{ parentPath: parentPath, childIDs: childIDs, }) }广播机制的底层实现两个事件最终都走util.BroadcastByType其实现位于 kernel/util/websocket.go约 L86-L97。该函数通过SessionsByType(typ)收集所有type为main的 WebSocket 会话基于 melody 库的 session 管理并向每个会话写入一条携带cmd即事件名与data的事件消息func BroadcastByType(typ, cmd string, code int, msg string, data any) { typeSessions : SessionsByType(typ) for _, sess : range typeSessions { event : NewResult() event.Cmd cmd event.Code code event.Msg msg event.Data data sess.Write(event.Bytes()) } }这意味着插件可以通过思源的 WebSocket 事件通道订阅filetreeSortChanged/notebookSortChanged在用户拖拽排序文件树或笔记本后即时感知变化进而实现排序状态同步到自定义视图或按排序批量处理文档等联动功能。这两个事件在插件生态中可作为观察文档组织结构的标准化信号使用。源码深挖SIYUAN_TESSERACT_TIMEOUT超时机制的完整实现图片 OCR 的超时控制是 v3.4.1 中可配置性最强的一项变更值得从源码层面完整理解。相关逻辑集中在 kernel/util/ocr.go 的Tesseract函数约 L246-L269timeout : 7000 timeoutEnv : os.Getenv(SIYUAN_TESSERACT_TIMEOUT) if ! timeoutEnv { if timeoutParsed, parseErr : strconv.Atoi(timeoutEnv); nil parseErr { timeout timeoutParsed } else { logging.LogWarnf(parse tesseract timeout [%s] failed: %s, timeoutEnv, parseErr) } } ctx, cancel : context.WithTimeout(context.Background(), time.Duration(timeout)*time.Millisecond) defer cancel()实现要点如下默认值 7000未设置环境变量时OCR 超时默认为 7000 毫秒7 秒与旧版本行为保持一致升级无感知。单位是毫秒环境变量的数值按毫秒解析设置SIYUAN_TESSERACT_TIMEOUT10000即表示 10 秒。非法值安全回退若环境变量无法被strconv.Atoi解析为整数内核不会崩溃而是记录一条parse tesseract timeout [...] failed的警告日志并继续使用默认 7000ms。超时通过context.WithTimeout生效OCR 子进程以exec.CommandContext启动超时到达后ctx.Err()返回context.DeadlineExceeded内核会记录tesseract [...] timeout [7000ms]警告日志并放弃本次识别避免 tesseract 进程长时间占用资源。配套的稳定性设计Tesseract函数内部还使用全局互斥锁tesseractOCRLock将 OCR 串行化执行注释明确说明这是为提升稳定性而引入对应 issue #7265同时对图片大小做了限制——超过TesseractMaxSize2 MB的图片会直接跳过识别。这些约束配合可配置超时共同保障了 OCR 在低性能设备与超大图片场景下的健壮性。实际调用的 tesseract 命令行位于同函数下方约 L258tesseract -c debug_file/dev/null 图片绝对路径 stdout -l 语言列表以连接 tsv即使用-l指定识别语言多个语言用连接如chi_simeng并以 TSV 格式输出到 stdout内核随后解析 TSV 数据生成带坐标的 OCR 文本块。此外 OCR 功能默认仅在标准容器ContainerStd环境下启用且受TesseractEnabled开关控制启用状态与最大文件大小等参数在 kernel/util/ocr.go 中初始化并记录日志tesseract-ocr enabled [ver..., maxSize..., langs...]。使用建议在部署或自托管思源内核时若你的工作空间包含大量高分辨率截图且设备性能有限可通过环境变量调整 OCR 超时# 将 OCR 超时调整为 15 秒默认 7000ms SIYUAN_TESSERACT_TIMEOUT15000 ./kernel若 OCR 频繁超时且大量图片识别失败建议优先排查图片体积超过 2 MB 的图片本就不会被识别与 tesseract 语言包是否完整安装再考虑适当调大超时值。版本信息与下载v3.4.1 变更日志同时提供英文v3.4.1.md、简体中文v3.4.1_zh_CN.md与繁体中文v3.4.1_zh_CHT.md三个版本便于不同语言用户对照查阅。安装包可通过思源官方下载页获取完整的历史变更记录可参阅仓库根目录的 CHANGELOG.md 及 app/changelogs 目录下的各版本日志。小结v3.4.1 是一个典型的细节密集型维护版本数据库复制语义的修正、搜索定位的高亮居中、移动端系统打印与退出流程的补齐体现了对高频操作体验的持续投入S3 同步崩溃的修复则具有明确的稳定性价值而SIYUAN_TESSERACT_TIMEOUT环境变量与 Eventbus 新事件为运维人员与插件开发者分别提供了可配置性与可观测性上的增量。对于开发者而言通过filetreeSortChanged/notebookSortChanged事件订阅文档结构变化结合 kernel/util/websocket.go 中的 WebSocket 广播机制可以构建出与思源文件树深度联动的第三方能力。【免费下载链接】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），仅供参考