SiYuan v2.9.8 版本详解闪卡 FSRSv4、Mermaid 升级与同步健壮性改进【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan本篇文章基于思源笔记官方发布记录 v2.9.8_zh_CN.md 展开系统梳理 v2.9.8 在改进功能、缺陷修复、开发者接口三个维度的全部变更并结合当前仓库源码说明关键能力闪卡间隔重复、Mermaid 渲染、资源导出 API的底层实现。读完本文你将清楚了解该版本的升级价值、每个变更点的实际影响以及开发者如何利用其中新增的内核 API 与前端接口。版本概述与升级建议v2.9.8 是一个以稳定性与健壮性为主的细节修复版本官方建议升级。其主要工作集中在以下三个方向功能改进涉及 Word 导出、数据同步、闪卡、Mermaid 渲染、属性面板、local.json配置健壮性等 10 项缺陷修复覆盖搜索、大纲、资源文件、拖拽编辑、文档树等 11 个问题开发者能力属性视图新增 URL 列、日期列过滤与计算、资源导出新 API、数据库索引提交事件推送、闪卡复习日志持久化等 11 项。从变更密度看该版本既是同步与闪卡两个数据可靠性关键模块的一次加固也是属性视图与插件 API 生态的一次扩容。改进功能详解1. 导出 Word 文档时删除目标位置文件此前重复导出 Word 文档到同一位置时目标文件若已存在可能出现覆盖不彻底或残留问题。v2.9.8 在导出前先清理目标位置文件避免新旧文件混杂。这与 导出模块 中其他导出流程先写临时文件、再交付的思路一致——导出的本质是生成一份全新的、自洽的文件而不是增量修改既有文件。2. 改进弹出层位置弹出层popover / dialog的定位算法在此版本得到修正避免在窗口边缘、滚动场景下弹出层越界或被遮挡。该改动属于编辑器 UI 基础体验的打磨影响菜单、提示、预览等所有使用弹出层的场景。3. 改进数据同步锁数据同步是思源内核中最容易产生并发竞争的部分之一。v2.9.8 对同步锁的持有粒度与释放时机进行了加固降低同步与本地编辑、索引重建之间的竞态风险。这与 sync 相关内核文件、job 定时任务 中同步调度逻辑共同构成同步可靠性的保障体系。4. 改进闪卡数据读写稳定性闪卡Flashcard数据的读写稳定性被重点加强。在 闪卡实现 中卡片数据经由deck.Review、deck.SaveLog等调用链持久化v2.9.8 针对复习过程中的并发读写与异常中断场景做了加固避免复习时卡片状态丢失或牌组文件损坏。5. 升级闪卡间隔重复算法 FSRSv4闪卡复习的核心调度算法从早期版本升级为FSRS v4。从当前仓库的依赖与配置代码可以看到内核直接引入github.com/open-spaced-repetition/go-fsrs/v3见 flashcard.go并使用 FSRS 官方的默认参数体系。在 内核配置结构 中FSRS 相关可调参数被持久化为// Apply result optimized by FSRS optimizer RequestRetention float64 json:requestRetention // 期望记忆保持率 MaximumInterval int json:maximumInterval // 最大复习间隔 Weights string json:weights // FSRS 权重19 个默认值由fsrs.DefaultParam()与fsrs.DefaultWeights()初始化见 NewFlashcard并提供了 DefaultFSRSWeights 将权重序列化为逗号分隔字符串写入配置。这意味着高级用户可以通过设置界面调整记忆保持率、最大间隔乃至权重向量从而让调度策略贴合个人记忆曲线。同时该版本中闪卡结构还包含新卡/复习卡上限、多种制卡来源开关mark、list、superBlock、heading、deck以及复习模式ReviewMode等控制项详见 flashcard.go。复习调度入口ReviewFlashcard见 flashcard.go会先通过reviewCardCache缓存复习前的卡片快照以支持撤销再执行deck.Review并将结果通过deck.SaveLog写入复习日志。6. 升级 Mermaid 10Mermaid 图表渲染引擎升级到 10 版本带来更完善的语法支持与渲染稳定性。从当前仓库前端实现 mermaidRender.ts 可以看到该渲染管线的工作方式通过addScript动态加载mermaid.min.js并以data-rendertrue标记避免重复渲染L6-L12注册 ZenUML 外部时序图与图标包后调用window.mermaid.initialize(config)配置中显式设置securityLevel: loose以兼容渲染L26-L50渲染结果会经过DOMPurify.sanitize清洗并保留foreignObject、xlink:href等必要属性L101-L107。Mermaid 渲染对暗色主题也有适配当appearance.mode 1时自动切换theme dark。7. 鼠标移入配置项时统一按钮显示效果统一设置界面中配置项在鼠标悬停时的按钮展示样式含“恢复默认值”等按钮提升设置项的可发现性与交互一致性。8. 改进 local.json 损坏时的健壮性local.json是思源本地配置的持久化文件一旦因断电、异常退出等导致 JSON 损坏可能导致启动失败或配置丢失。v2.9.8 增强了该文件读取失败时的容错处理使内核能够以更稳妥的方式恢复或重建配置避免数据不可用。9. 数据同步前检查本地数据分块完整性思源的仓库repository以分块chunk方式存储数据。该版本在同步上传之前增加本地分块完整性校验提前发现分块缺失或哈希不一致的问题从源头避免把不完整的数据推送到云端。这是同步可靠性链路中的重要一环与数据仓库实现 repository.go 及分块相关的文件系统逻辑配合工作。10. 改进属性面板属性面板Attribute Panel在交互与展示层面得到改进为后续属性视图能力的扩展见下文“开发者”部分铺垫基础。修复缺陷详解搜索与大纲导航搜索结果预览时面包屑不正确修复了搜索结果预览面板中面包屑定位错误的问题确保预览时能看到准确所在路径。大纲跳转到嵌入的标题块而非实际块此前大纲点击可能跳到嵌入块iframe 内的标题块而不是文档中的实际标题位置该版本改为跳转到真实的目标块。资源文件与图片处理以.开头的资源文件不应被识别为已丢失修复了将隐藏文件如.DS_Store、临时文件等以点号开头的文件误判为“已丢失资源文件”的问题避免误报和误清理。资源文件搜索乱码修复了在资源搜索场景下对非 UTF-8 命名或特殊编码文件名的解析乱码问题。插入图片链接后按Esc未保存链接地址在图片链接编辑浮层中此前按Esc取消时可能丢失已输入的链接地址现改为正确保留。块编辑与拖拽将非纯文本行级元素转换为块引用时锚文本重复修复了包含行级元素如行内代码、加粗等的内容被转换为块引用时锚文本出现重复的问题。拖拽靠左后不应选择所有块修复了拖拽块靠左停靠时误触发全选的问题。分屏后拖拽列表项导致数据丢失分屏多窗口场景下拖拽列表项可能造成数据丢失该版本进行了修复——此类块级操作的数据安全与 事务处理 的合并与回滚机制密切相关。文档树悬停文档树计数渲染异常修复了鼠标悬停文档树条目时计数如子文档数、引用数渲染异常的问题。文档树最大列出数判断问题修复了文档树在达到“最大列出数”阈值时判断逻辑不正确、可能超量或提前截断的问题来自社区 PR。开发者相关变更本版本对属性视图Attribute View / 数据库和插件 API的投入尤其值得开发者关注。属性视图能力扩充属性视图搜索或添加新文档可在属性视图中直接搜索已有文档并添加为行或将新文档加入视图极大提升数据录入效率。属性视图日期列过滤日期列支持按时间段/条件进行过滤。属性视图日期列计算日期列支持聚合计算如最早、最晚等。属性视图支持 URL 列新增 URL 列类型用于存储与展示链接。支持从文档树拖拽文档插入行可以直接把文档树中的文档拖入属性视图生成新行。这些能力使属性视图内核侧实现在 av 目录从“结构化展示”向“可搜索、可计算的轻量数据库”演进。前端实现中Av相关逻辑位于 app/src/protyle 与编辑器块级属性实现中。块属性面板更好地显示属性视图字段当块关联了属性视图字段时块属性面板Alt点击弹出的面板现在能更友好地展示这些字段及其值打通“块 — 属性视图字段”之间的信息桥。推送数据库索引提交事件内核在数据库索引提交完成后会推送对应事件使插件或前端可以感知“索引已刷新”的时刻并据此刷新自己的数据视图避免在索引未就绪时读取到陈旧结果。持久化闪卡复习日志记录复习日志review log被正式持久化落盘。在 ReviewFlashcard 的实现中每次复习除更新卡片调度状态外还会调用deck.SaveLog(log)写入日志前端也可据此实现复习历史回看、撤销依赖reviewCardCache等能力。内核 API/api/export/exportResources导出文件和文件夹该版本新增内核 APIPOST /api/export/exportResources用于按资源路径列表导出文件或文件夹。其服务端入口定义在 exportResources核心实现在 ExportResourcesfunc ExportResources(resourcePaths []string, mainName string) (exportFilePath string, err error)实现要点先调用FlushTxQueue()冲刷待处理事务保证导出数据一致检测资源是否位于加密笔记本若是则全程HoldBoxReadLock防止导出期间加密箱被锁定或写回明文L711-L725使用随机exportID作为物理临时目录mainName仅用于用户可见的 ZIP 文件名与包内顶层目录名L727-L739导出完成后清理临时目录失败时同步移除残留的.zip与.partial文件L744-L750。对于需要“批量备份资源”或“将资源打包转移”的插件开发者而言此 API 比逐文件下载更高效。前端 API 兼容性“Protyle” 渲染参数兼容前端 Protyle 渲染相关 API 增加参数兼容处理降低插件在不同渲染上下文编辑器、导出预览、动态插入等下调用时的适配成本。当前仓库中ProtyleMethod见 ProtyleMethod.ts将mermaidRender等渲染能力暴露给插件使用。“confirm” 对话框回调添加参数插件调用confirm对话框时回调函数新增参数传递使插件在确认/取消后可获得更完整的上下文信息。总结v2.9.8 的价值可以概括为三句话更稳同步锁、同步前分块完整性检查、闪卡读写、local.json容错等一系列数据可靠性加固让本地数据与云端数据更值得信赖更强闪卡调度升级 FSRS v4内核基于go-fsrs/v3相关可调参数已持久化到 配置结构、Mermaid 渲染升级至 10更开放属性视图新增 URL 列、日期列过滤与计算、文档拖拽入视图并新增/api/export/exportResources资源导出 API 与数据库索引提交事件为第三方插件提供了新的能力入口。对普通用户而言直接升级即可获得上述稳定性收益对插件开发者则建议重点验证属性视图相关 UI 回调与导出 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），仅供参考 SiYuan v2.9.8 版本详解：闪卡 FSRSv4、Mermaid 升级与同步健壮性改进
SiYuan v2.9.8 版本详解闪卡 FSRSv4、Mermaid 升级与同步健壮性改进【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan本篇文章基于思源笔记官方发布记录 v2.9.8_zh_CN.md 展开系统梳理 v2.9.8 在改进功能、缺陷修复、开发者接口三个维度的全部变更并结合当前仓库源码说明关键能力闪卡间隔重复、Mermaid 渲染、资源导出 API的底层实现。读完本文你将清楚了解该版本的升级价值、每个变更点的实际影响以及开发者如何利用其中新增的内核 API 与前端接口。版本概述与升级建议v2.9.8 是一个以稳定性与健壮性为主的细节修复版本官方建议升级。其主要工作集中在以下三个方向功能改进涉及 Word 导出、数据同步、闪卡、Mermaid 渲染、属性面板、local.json配置健壮性等 10 项缺陷修复覆盖搜索、大纲、资源文件、拖拽编辑、文档树等 11 个问题开发者能力属性视图新增 URL 列、日期列过滤与计算、资源导出新 API、数据库索引提交事件推送、闪卡复习日志持久化等 11 项。从变更密度看该版本既是同步与闪卡两个数据可靠性关键模块的一次加固也是属性视图与插件 API 生态的一次扩容。改进功能详解1. 导出 Word 文档时删除目标位置文件此前重复导出 Word 文档到同一位置时目标文件若已存在可能出现覆盖不彻底或残留问题。v2.9.8 在导出前先清理目标位置文件避免新旧文件混杂。这与 导出模块 中其他导出流程先写临时文件、再交付的思路一致——导出的本质是生成一份全新的、自洽的文件而不是增量修改既有文件。2. 改进弹出层位置弹出层popover / dialog的定位算法在此版本得到修正避免在窗口边缘、滚动场景下弹出层越界或被遮挡。该改动属于编辑器 UI 基础体验的打磨影响菜单、提示、预览等所有使用弹出层的场景。3. 改进数据同步锁数据同步是思源内核中最容易产生并发竞争的部分之一。v2.9.8 对同步锁的持有粒度与释放时机进行了加固降低同步与本地编辑、索引重建之间的竞态风险。这与 sync 相关内核文件、job 定时任务 中同步调度逻辑共同构成同步可靠性的保障体系。4. 改进闪卡数据读写稳定性闪卡Flashcard数据的读写稳定性被重点加强。在 闪卡实现 中卡片数据经由deck.Review、deck.SaveLog等调用链持久化v2.9.8 针对复习过程中的并发读写与异常中断场景做了加固避免复习时卡片状态丢失或牌组文件损坏。5. 升级闪卡间隔重复算法 FSRSv4闪卡复习的核心调度算法从早期版本升级为FSRS v4。从当前仓库的依赖与配置代码可以看到内核直接引入github.com/open-spaced-repetition/go-fsrs/v3见 flashcard.go并使用 FSRS 官方的默认参数体系。在 内核配置结构 中FSRS 相关可调参数被持久化为// Apply result optimized by FSRS optimizer RequestRetention float64 json:requestRetention // 期望记忆保持率 MaximumInterval int json:maximumInterval // 最大复习间隔 Weights string json:weights // FSRS 权重19 个默认值由fsrs.DefaultParam()与fsrs.DefaultWeights()初始化见 NewFlashcard并提供了 DefaultFSRSWeights 将权重序列化为逗号分隔字符串写入配置。这意味着高级用户可以通过设置界面调整记忆保持率、最大间隔乃至权重向量从而让调度策略贴合个人记忆曲线。同时该版本中闪卡结构还包含新卡/复习卡上限、多种制卡来源开关mark、list、superBlock、heading、deck以及复习模式ReviewMode等控制项详见 flashcard.go。复习调度入口ReviewFlashcard见 flashcard.go会先通过reviewCardCache缓存复习前的卡片快照以支持撤销再执行deck.Review并将结果通过deck.SaveLog写入复习日志。6. 升级 Mermaid 10Mermaid 图表渲染引擎升级到 10 版本带来更完善的语法支持与渲染稳定性。从当前仓库前端实现 mermaidRender.ts 可以看到该渲染管线的工作方式通过addScript动态加载mermaid.min.js并以data-rendertrue标记避免重复渲染L6-L12注册 ZenUML 外部时序图与图标包后调用window.mermaid.initialize(config)配置中显式设置securityLevel: loose以兼容渲染L26-L50渲染结果会经过DOMPurify.sanitize清洗并保留foreignObject、xlink:href等必要属性L101-L107。Mermaid 渲染对暗色主题也有适配当appearance.mode 1时自动切换theme dark。7. 鼠标移入配置项时统一按钮显示效果统一设置界面中配置项在鼠标悬停时的按钮展示样式含“恢复默认值”等按钮提升设置项的可发现性与交互一致性。8. 改进 local.json 损坏时的健壮性local.json是思源本地配置的持久化文件一旦因断电、异常退出等导致 JSON 损坏可能导致启动失败或配置丢失。v2.9.8 增强了该文件读取失败时的容错处理使内核能够以更稳妥的方式恢复或重建配置避免数据不可用。9. 数据同步前检查本地数据分块完整性思源的仓库repository以分块chunk方式存储数据。该版本在同步上传之前增加本地分块完整性校验提前发现分块缺失或哈希不一致的问题从源头避免把不完整的数据推送到云端。这是同步可靠性链路中的重要一环与数据仓库实现 repository.go 及分块相关的文件系统逻辑配合工作。10. 改进属性面板属性面板Attribute Panel在交互与展示层面得到改进为后续属性视图能力的扩展见下文“开发者”部分铺垫基础。修复缺陷详解搜索与大纲导航搜索结果预览时面包屑不正确修复了搜索结果预览面板中面包屑定位错误的问题确保预览时能看到准确所在路径。大纲跳转到嵌入的标题块而非实际块此前大纲点击可能跳到嵌入块iframe 内的标题块而不是文档中的实际标题位置该版本改为跳转到真实的目标块。资源文件与图片处理以.开头的资源文件不应被识别为已丢失修复了将隐藏文件如.DS_Store、临时文件等以点号开头的文件误判为“已丢失资源文件”的问题避免误报和误清理。资源文件搜索乱码修复了在资源搜索场景下对非 UTF-8 命名或特殊编码文件名的解析乱码问题。插入图片链接后按Esc未保存链接地址在图片链接编辑浮层中此前按Esc取消时可能丢失已输入的链接地址现改为正确保留。块编辑与拖拽将非纯文本行级元素转换为块引用时锚文本重复修复了包含行级元素如行内代码、加粗等的内容被转换为块引用时锚文本出现重复的问题。拖拽靠左后不应选择所有块修复了拖拽块靠左停靠时误触发全选的问题。分屏后拖拽列表项导致数据丢失分屏多窗口场景下拖拽列表项可能造成数据丢失该版本进行了修复——此类块级操作的数据安全与 事务处理 的合并与回滚机制密切相关。文档树悬停文档树计数渲染异常修复了鼠标悬停文档树条目时计数如子文档数、引用数渲染异常的问题。文档树最大列出数判断问题修复了文档树在达到“最大列出数”阈值时判断逻辑不正确、可能超量或提前截断的问题来自社区 PR。开发者相关变更本版本对属性视图Attribute View / 数据库和插件 API的投入尤其值得开发者关注。属性视图能力扩充属性视图搜索或添加新文档可在属性视图中直接搜索已有文档并添加为行或将新文档加入视图极大提升数据录入效率。属性视图日期列过滤日期列支持按时间段/条件进行过滤。属性视图日期列计算日期列支持聚合计算如最早、最晚等。属性视图支持 URL 列新增 URL 列类型用于存储与展示链接。支持从文档树拖拽文档插入行可以直接把文档树中的文档拖入属性视图生成新行。这些能力使属性视图内核侧实现在 av 目录从“结构化展示”向“可搜索、可计算的轻量数据库”演进。前端实现中Av相关逻辑位于 app/src/protyle 与编辑器块级属性实现中。块属性面板更好地显示属性视图字段当块关联了属性视图字段时块属性面板Alt点击弹出的面板现在能更友好地展示这些字段及其值打通“块 — 属性视图字段”之间的信息桥。推送数据库索引提交事件内核在数据库索引提交完成后会推送对应事件使插件或前端可以感知“索引已刷新”的时刻并据此刷新自己的数据视图避免在索引未就绪时读取到陈旧结果。持久化闪卡复习日志记录复习日志review log被正式持久化落盘。在 ReviewFlashcard 的实现中每次复习除更新卡片调度状态外还会调用deck.SaveLog(log)写入日志前端也可据此实现复习历史回看、撤销依赖reviewCardCache等能力。内核 API/api/export/exportResources导出文件和文件夹该版本新增内核 APIPOST /api/export/exportResources用于按资源路径列表导出文件或文件夹。其服务端入口定义在 exportResources核心实现在 ExportResourcesfunc ExportResources(resourcePaths []string, mainName string) (exportFilePath string, err error)实现要点先调用FlushTxQueue()冲刷待处理事务保证导出数据一致检测资源是否位于加密笔记本若是则全程HoldBoxReadLock防止导出期间加密箱被锁定或写回明文L711-L725使用随机exportID作为物理临时目录mainName仅用于用户可见的 ZIP 文件名与包内顶层目录名L727-L739导出完成后清理临时目录失败时同步移除残留的.zip与.partial文件L744-L750。对于需要“批量备份资源”或“将资源打包转移”的插件开发者而言此 API 比逐文件下载更高效。前端 API 兼容性“Protyle” 渲染参数兼容前端 Protyle 渲染相关 API 增加参数兼容处理降低插件在不同渲染上下文编辑器、导出预览、动态插入等下调用时的适配成本。当前仓库中ProtyleMethod见 ProtyleMethod.ts将mermaidRender等渲染能力暴露给插件使用。“confirm” 对话框回调添加参数插件调用confirm对话框时回调函数新增参数传递使插件在确认/取消后可获得更完整的上下文信息。总结v2.9.8 的价值可以概括为三句话更稳同步锁、同步前分块完整性检查、闪卡读写、local.json容错等一系列数据可靠性加固让本地数据与云端数据更值得信赖更强闪卡调度升级 FSRS v4内核基于go-fsrs/v3相关可调参数已持久化到 配置结构、Mermaid 渲染升级至 10更开放属性视图新增 URL 列、日期列过滤与计算、文档拖拽入视图并新增/api/export/exportResources资源导出 API 与数据库索引提交事件为第三方插件提供了新的能力入口。对普通用户而言直接升级即可获得上述稳定性收益对插件开发者则建议重点验证属性视图相关 UI 回调与导出 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），仅供参考