SiYuan v3.1.9 版本更新深度解析数据库搜索、同步超时配置与新开发者 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.1.9_zh_CN.md 为核心骨架结合当前仓库内核Go与前端TypeScript源码逐条解析 v3.1.9 的改进功能、缺陷修复、开发重构与面向开发者的新增接口。读完本文你将掌握该版本在编辑体验、数据库视图、数据同步、导出性能等方面的具体变化并能直接使用新增的getDocsInfo内核 API 与exitSiYuan插件方法。版本概述v3.1.9 是 SiYuan 3.1.x 系列的一个稳定性维护版本。官方在更新日志开篇即给出结论此版本改进了很多细节并修复了一些缺陷建议升级。整个版本共包含约 30 条改进、6 条缺陷修复、1 条文档改进、4 条开发重构以及 3 条面向开发者的新增能力覆盖面从编辑器交互、数据库视图、数据同步、导出性能到国际化与插件系统。本文后续内容按更新日志的五个板块改进功能、修复缺陷、改进文档、开发重构、开发者展开并对其中可落地到源码的关键点做纵深剖析。改进功能编辑体验与块操作超级块中按 Enter 创建新块此前在超级块Super Block内部按下 Enter 的行为在某些场景下不够直观v3.1.9 对其进行了改进使在超级块中创建新块的行为更符合预期。该改动属于编辑器内核 Protyle 渲染层的行为调整对应的渲染逻辑维护在 app/src/protyle 目录下。相邻行级元素的合并行级元素Inline Elements如加粗、行内代码、超链接等在相邻场景下的合并策略得到改进减少了编辑过程中不必要的元素分裂使光标定位与样式连续性更稳定。超链接元素支持以多种格式复制超链接a元素现在支持以多种格式复制例如复制时携带链接文本与目标地址的对应关系便于粘贴到其他应用时保留语义。结合剪贴板处理前端相关逻辑位于 app/src/util 与 kernel/util/clipboard.go。Alt拖动文档树拖入编辑器插入块引用v3.1.9 支持在按住Alt的同时将文档树Doc Tree上的文档直接拖动到编辑器中以**块引用Block Reference**的形式插入。这是文档间快速关联的实用操作相比传统的手动复制文档锚文本再转引用拖拽方式显著降低了建立引用网络的操作成本。文档树交互逻辑可参考 app/src/menus/workspace.ts 中工作区菜单对树操作的整体组织方式。改进块拖动块拖动的稳定性与命中判定得到进一步优化拖拽块到其他位置包括跨文档时的落点计算更准确。按下向下键后光标移动到下一行开头编辑器中按下向下方向键后光标将移动至下一行的开头而非保持列位置这是对中文与英文混排场景下光标移动体验的细节修正属于 Protyle 编辑器按键处理逻辑的改动。为某些块的背景颜色添加透明度部分块如标记块、自定义样式块的背景颜色现在支持透明通道样式表现上可以与主题背景更自然地融合。块背景色的样式变量定义在 app/src/assets/scss 的样式体系中。改进功能数据库视图支持数据库视图搜索这是本版本在数据库Attribute View属性视图方向最重要的能力补充数据库视图现在支持搜索。在 kernel/av 目录中维护了数据库视图的过滤filter.go、排序sort.go、分组group.go与布局layout_table.go、layout_kanban.go、layout_gallery.go等核心逻辑搜索能力与既有过滤体系协同工作使视图在数据量增大后仍能快速定位记录。改进绑定容器块的数据库主键内容更新当数据库主键Primary Key绑定的容器块如列表项、段落块内容发生变化时数据库视图中的对应记录会及时同步更新避免视图内显示陈旧内容。改进移动端的数据库编辑移动端iOS/Android上编辑数据库视图的操作体验得到改进相关前端代码位于 app/src/mobile 与 app/src/protyle。改进功能同步、索引与资源管理自动清理官方云端 30 天前的未引用数据快照针对官方云端存储SiYuan Cloud的数据快照v3.1.9 增加了自动清理机制超过 30 天的未引用数据快照会被自动清理从而帮助用户控制云端存储占用。需要注意的是该机制仅针对官方云端同步的数据快照本地数据不受影响自托管 S3/WebDAV 场景下的快照策略以同步设置为准。同步相关的云端存储类型ProviderS3、ProviderWebDAV与超时配置定义在 kernel/conf/sync.go。改进 WebDAV/S3 数据同步请求超时设置v3.1.9 对 WebDAV 与 S3 数据同步的请求超时时间设置进行了改进。从源码结构看两种存储协议的超时字段分别定义为S3.TimeoutS3 协议请求超时时间单位秒kernel/conf/sync.goWebDAV.TimeoutWebDAV 协议请求超时时间单位秒kernel/conf/sync.go这意味着用户可以在设置界面针对不同存储提供商分别配置超时阈值以适配网络状况较差的服务器环境减少同步任务因请求挂起而长时间占用队列的情况。改进数据索引性能数据索引Data Index构建与增量更新的性能得到优化。索引相关实现集中在 kernel/sql 目录index_queue.go、database.go 等改进方向包括减少不必要的重建与批量写入优化具体收益体现为打开工作空间与文档检索时的响应速度。删除或回滚文档后自动刷新引用计数文档被删除或从历史版本回滚后引用计数Ref Count现在会自动刷新避免文档树与反链面板中残留过期的引用统计保证反向链接数据的准确性。引用统计相关的块信息模型见 kernel/model/blockinfo.go。改进导出 .sy.zip 笔记本的性能笔记本整体导出为.sy.zip的性能得到提升尤其对包含大量资源文件与历史数据的工作空间打包耗时显著下降。导出流程涉及 kernel/model/export.go 与 kernel/model/export_merge.go。改进嵌入块的标题级别导出嵌入块Embed Block即引用另一文档的块在导出时标题Heading的级别处理得到修正导出的 Markdown/Word 文档中嵌入内容不会再出现错误的标题层级。改进 HTML 公式剪藏通过浏览器剪藏扩展抓取包含公式MathML 或 LaTeX的 HTML 内容时公式的解析与转换更准确避免剪藏后公式乱码。剪藏相关的内核处理见 kernel/util/webfetch.go。国际化新增四种语言支持v3.1.9 的国际化翻译新增/完善了希伯来语、德语、波兰语和俄语支持。对应语言文件已存在于仓库 app/appearance/langs 目录he.json希伯来语de.json德语pl.json波兰语ru.json俄语语言切换后设置界面与编辑器 UI 会加载对应语言包多语言团队协作时可选择各自熟悉的界面语言。移动端“关于”中显示导入/导出设置移动端设置中的“关于”页面现在会显示导入/导出相关设置入口方便用户在移动设备上快速触达数据迁移功能。修复缺陷v3.1.9 共修复了 6 个缺陷具体如下缺陷影响场景无法在代码块中替换gt;代码块中查找/替换包含转义序列的文本时失效搜索忽略在某些情况下不起作用“搜索忽略”配置如忽略指定块在特定搜索条件下未生效无法在 iOS 16.x 上打开资源文件iOS 16.x 系统上点击图片、附件等资源无法打开嵌入标题块后折叠和展开异常嵌入的标题块在文档中折叠/展开时行为错乱设置闪卡到期时间不起作用闪卡Flashcard的到期时间设置未按预期生效移动端无法启用“允许执行 HTML 块内脚本”选项移动端该开关设置被保存但无法生效这些修复大多属于编辑器与移动端容器层的回归性问题。其中“允许执行 HTML 块内脚本”选项的解析与安全策略可在内核配置中追溯前端开关位于设置界面app/src/config 目录。改进文档用户指南中的搜索忽略章节官方用户指南内置帮助文档中新增/改进了“搜索忽略”章节对搜索忽略的适用规则与限制做了更清晰的说明。内置帮助文档以.sy文件形式存在于 app/guide 目录。开发重构依赖升级与平台适配组件变更影响PDF.js升级至 v4.7.85PDF 预览与标注渲染性能、兼容性提升Electron升级至 v32.2.0桌面端Windows/macOS/LinuxChromium 内核版本升级安全性与渲染能力提升Pandoc升级至 v3.5导入/导出 Markdown、Word、EPUB 等格式的转换能力增强当前仓库的桌面端打包与依赖声明可见于 app/package.json其中electron依赖已随后续版本演进至更高版本与 app/electron-builder.yml 等构建配置。另外SiYuan Flatpak 打包版本的配置目录从$HOME调整为使用$XDG_CONFIG_HOME以符合 Flatpak 的沙箱规范避免在部分 Linux 发行版上因家目录权限问题导致配置无法读写。开发者新增接口与方法为工作区菜单的按钮添加data-id属性工作区菜单中的按钮元素现在带有data-id属性方便插件或脚本通过选择器精准定位菜单项并绑定自定义事件降低了对菜单 DOM 结构变化的耦合。工作区菜单实现在 app/src/menus/workspace.ts。新增内核 API/api/block/getDocsInfov3.1.9 为内核新增了批量查询文档信息的 API/api/block/getDocsInfo。从源码看kernel/api/block.go该接口的请求参数与行为如下ids文档 ID 数组必填支持一次批量查询多个文档refCount布尔值是否查询引用计数av布尔值是否查询关联的数据库视图Attribute View信息接口在 kernel/api/router.go 中注册路由受model.CheckAuth认证保护。其底层实现为 kernel/model/blockinfo.go 中的GetDocsInfo函数返回[]*BlockInfo数组每个文档条目与单文档接口getDocInfokernel/api/block.go的返回结构一致便于调用方统一处理。典型的调用示例HTTP POST JSON{ ids: [20210808180117-6v0mkxr, 20230405172236-pg3l9eu], refCount: true, av: false }响应中的data为文档信息数组每条包含文档的标题、路径、更新时间、字数统计以及当refCount为 true 时引用计数等字段。该 API 的价值在于插件或外部脚本可以一次 RPC 拿到多个文档的元信息而不必逐文档调用单查接口显著减少了批量场景下的请求次数。此外接口在只读角色上下文发布场景下会通过FilterBlockInfoByPublishAccess对返回信息做访问过滤避免泄露未授权文档详情。新增插件方法exitSiYuan插件系统新增了exitSiYuan方法插件可通过它触发 SiYuan 退出流程。该方法在前端暴露于插件 API 对象中app/src/plugin/API.ts其实现位于 app/src/dialog/processSystem.ts默认先调用内核接口/api/system/exit携带force: false与setCurrentWorkspace走正常退出流程保存滚动位置、关闭工作空间若内核返回 code 1同步执行失败例如有未完成的数据写入则向用户展示错误提示与“强制退出”按钮点击后以force: true重试若返回 code 2提示存在新安装包则引导用户进入更新流程在桌面端Electron通过 IPC 通知主进程退出移动端则分别调用 Android/iOS/Harmony 原生的退出接口。因此插件调用exitSiYuan()与用户在菜单中点击“退出”走的是同一套完整流程包括数据落盘保护插件不应自行调用浏览器window.close()绕过该流程。该方法在工作区菜单app/src/menus/workspace.ts等多处 UI 中同样被复用。升级建议该版本修复了代码块替换、iOS 16.x 资源打开、闪卡到期时间等若干影响日常使用的缺陷同时带来数据库搜索、超链接多格式复制等实用能力建议所有用户升级。升级前建议通过“设置 → 关于 → 导出数据”或导出.sy.zip备份工作空间该版本的导出性能改进恰好让备份过程更快。自托管同步WebDAV/S3用户可在升级后重新评估同步请求超时设置为不稳定的服务器环境配置更合理的超时值。插件开发者可立即使用/api/block/getDocsInfo批量查询文档信息并在需要退出应用时调用exitSiYuan以获得完整的退出保护流程。该版本对应的完整变更列表可对照英文版 v3.1.9.md 与繁体中文版 v3.1.9_zh_CHT.md 查阅其他历史版本的变更记录位于 app/changelogs 目录。【免费下载链接】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），仅供参考