★ FEATURED ARTICLE SiYuan v3.1.5 更新深度解读表情加载、FSRS-5 升级与新内核 API getPathByID【免费下载链接】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.5 官方变更日志v3.1.5_zh_CHT.md为主体逐条梳理该版本的改进、修复与开发者接口变化并结合当前仓库内核源码kernel/api/filetree.go、kernel/model/flashcard.go、kernel/model/upload.go 等解释每条变更背后的实现位置与机制帮助开发者判断升级收益、理解内核 API 设计并为插件/MCP 工具作者提供可直接调用的接口细节。版本概述v3.1.5 是一个典型的“细节打磨版本”官方概述原话为“此版本修复了一些细节缺陷建议升级。”变更内容分为五个板块改进功能8 项、修复缺陷4 项、开发重构1 项、开发者接口2 项。涉及的面覆盖编辑器输入体验、网页剪藏、历史回滚与索引策略、导出渲染以及闪卡间隔重复算法FSRS的底层升级。下面逐板块展开所有条目均可在仓库源码中找到对应实现。改进功能逐条解析改进编辑器表情符号加载该改进对应上游问题 #12241。从源码看编辑器表情面板的核心实现在 表情模块面板打开时并不一次性渲染全部表情而是通过filterEmoji先生成骨架 HTML非首屏的分类只保留data-index占位符lazyLoadEmoji使用浏览器IntersectionObserver监听.emojis__content面板滚动只有当分类真正进入视口时才由renderEmojiContent把data-index对应的表情批量渲染为button并移除占位标记lazyLoadEmoji 实现动态图标如日历图标同样采用data-src延迟填充的懒加载策略见lazyLoadEmojiImg实现。这种“视口懒加载 占位符回填”的结构使表情面板在表情库较大时依然保持打开速度。v3.1.5 的改进正是围绕该加载路径的细节优化。此外putEmojis会把自定义表情注册进 Lute 解析器注释中明确说明 Lute 为所有编辑器共享单例PutEmojis只需调用一次putEmojis 实现这也是表情加载链路的一部分。改良 CSDN 剪藏与链滴剪藏CSDN 剪藏问题 #12313与链滴剪藏问题 #12368属于网页剪藏解析器的站点适配改进。SiYuan 的剪藏流程是浏览器剪藏内容提交到内核后由内核的剪藏解析逻辑按站点特征提取正文再落盘为块。该版本针对两个中文内容站点的正文抓取规则做了调整属于规则层面的站点级修复仓库中对应的能力入口为剪藏导入相关接口使用者升级后直接重新剪藏受影响页面即可验证效果。改进代码块行号渲染与空格行行号错误该版本包含两条与代码块行号相关的记录改进代码块行号渲染问题 #12317优化编辑器中代码块行号 UI 的呈现修复仅含空格行导致的行号计算错误问题 #12346代码块中只包含空白字符的行此前会干扰行号计数本版本修复了该边界情况。行号渲染依赖块内容与行结构的逐行解析空格行属于典型的解析边界用例。对经常引用代码块行号的读者如文档注释、代码审阅场景这一修复保证了行号与实际行一一对应。回滚文档后仅重新索引当前文档该改进问题 #12320针对的是历史版本回滚后的索引刷新范围。内核中历史回滚的入口是 RollbackDocHistory它会从历史快照目录取回旧的.sy文档、写回工作区文档再触发索引更新。此前的行为是回滚后触发更大范围的重新索引v3.1.5 将范围收敛为“仅重新索引当前文档”显著缩小了索引队列的瞬时压力。值得注意的是回滚逻辑对加密笔记本有专门分支RollbackDocHistory通过getRollbackBox获取目标笔记本若原笔记本为加密且处于挂载状态则用原始 boxID 解密后再写回避免密文被误写入普通回滚笔记本相关注释。索引范围的收缩与这条写回路径是配套收益写回动作变精确索引动作也相应精确。改进分隔线输入与列表项编辑分隔线输入改进问题 #12340优化---等分隔线标记的触发时机减少误触发与漏触发列表项编辑改进问题 #12066优化列表块编辑时的行为细节。两者都属于 Markdown 快捷输入shortcut与块编辑的交互修正体现在编辑器前端对输入序列的判定逻辑中。不再限制编辑器中动态加载块的数量问题 #12359此前编辑器对“动态加载块”如嵌入块、引用块等按需加载外部内容的块的数量存在上限保护v3.1.5 移除了该数量限制。这意味着长文档中密集使用嵌入/动态块时不再受截断影响。从源码结构看块的动态加载由编辑器渲染管线按块类型分发移除上限后需要依赖块加载自身的性能控制这也是官方在同版本中同步优化其它渲染细节的背景之一。改进数据库关联字段绑定/解绑块问题 #12372属性视图数据库中“关联”类型字段的块绑定/解绑操作得到改进。关联字段的数据落在属性视图的关系表中仓库中对应实现位于 kernel/av/relation.go 与 kernel/sql/av.go 一层的属性视图关系处理逻辑。该改进使绑定/解绑块时的状态同步更可靠减少关联卡片数据与视图展示不一致的情况。修复缺陷逐条解析S3/WebDAV 无法获取云端快照列表问题 #12350在使用 S3 或 WebDAV 作为同步存储时云端快照列表拉取失败。快照列表能力服务于本地快照恢复场景内核同步模块的存储抽象层S3/WebDAV 适配器中相应列举接口在本版本修复。对自建云同步S3 兼容对象存储、WebDAV 服务器的用户这是恢复数据链路上的关键修复升级后建议重新验证一次“查看云端快照列表”操作。导出为 PDF/图片/HTML 时代码块未语法高亮问题 #12378导出产物中的代码块丢失语法高亮。SiYuan 导出链路基于 Lute 将块内容渲染为 HTML 再走 PDF/图片管线高亮缺失通常源于导出时高亮上下文未随渲染上下文一并传递。该修复保证了导出件与编辑器内所见一致的代码块着色涉及代码块较多的文档如技术笔记、讲义导出质量直接受益。其余缺陷修复列表项编辑问题 #12066的编辑行为修正代码块空格行行号计算错误问题 #12346见上文S3/WebDAV 云端快照列表问题 #12350见上文。开发重构升级到 FSRS-5这是本版本唯一的“开发重构”项问题 #12344值得单独展开。SiYuan 内置闪卡间隔重复复习系统依赖 FSRSFree Spaced Repetition Scheduler算法计算复习间隔内核通过github.com/open-spaced-repetition/go-fsrs/v3库接入 FSRSgo.mod 中声明了该依赖闪卡卡包以riff.Deck结构管理参数来自用户配置卡包加载入口 LoadFlashcards遍历数据目录下*.deck文件调用riff.LoadDeck时传入Conf.Flashcard.RequestRetention期望记忆率、Conf.Flashcard.MaximumInterval最大间隔与Conf.Flashcard.Weights算法权重向量复习动作 ReviewFlashcard按评价rating调用deck.Review更新卡片状态并落盘复习日志还维护了reviewCardCache/skipCardCache两个缓存以支持复习过程中的撤销与跳过待复习卡片调度 getDeckDueCards 调用链按笔记本、文档或卡包维度取卡受NewCardLimit新卡上限与ReviewCardLimit复习卡上限约束文档级还可通过 IAL 属性custom-riff-new-card-limit/custom-riff-review-card-limit单独覆盖文档级上限逻辑。升级到 FSRS-5 意味着上述复习间隔计算的权重与状态模型换用 FSRS 第五代参数体系。对使用者而言这是“无感但有效”的重构既有卡包数据保持可加载复习计划由新算法权重驱动对关心闪卡效果的开发者可通过闪卡配置中的权重参数验证行为变化。开发者接口变更新增内核 API/api/filetree/getPathByID问题/PR #12353。该 API 在当前仓库中的实现与注册均可直接查证路由注册于 router.go 第 155 行POST /api/filetree/getPathByID挂载了model.CheckAuth鉴权中间件处理函数 getPathByID接收 JSON 参数id块/文档 ID先用util.InvalidIDPattern校验 ID 合法性再调用model.GetPathByID(id)取出路径与所在笔记本响应体为{ code: 0, data: { path: /笔记/子文件夹/文档.sy, notebook: 笔记本ID } }与同文件中相邻的getHPathByID返回 hPath 层级路径实现不同getPathByID返回的是文件系统级完整路径加笔记本 ID这对插件或 MCP 工具作者非常实用——例如已知一个块 ID即可定位其物理文件位置而无需遍历文件树。调用示例需携带有效 tokencurl -X POST http://localhost:6806/api/filetree/getPathByID \ -H Authorization: Bearer token \ -d {id: 20230101000000-abcdefg}修复/api/asset/upload响应体succMap字段PR #12361。上传资源接口/api/asset/upload的响应体中包含succMap字段用于返回“上传成功文件名 → 资源路径”的映射。该字段的生成逻辑在内核 model/upload.go 的 InsertLocalAssets对每个本地文件按目标位置生成映射条目新建时为assets/文件名已存在时复用既有资源路径再由 asset API 层 将succMap装入 JSON 响应。本版本修复了该字段在特定分支下取值不正确的问题。所有依赖succMap解析上传结果的一方——包括仓库内的 CLI 命令cli/cmd/asset.go 直接打印该映射和 MCP 工具mcp/tools/asset.go 用它向模型汇报上传清单——都会因此受益修复后各入口拿到的路径映射保持一致。升级与下载建议v3.1.5 官方结论为“建议升级”对一般用户收益集中在编辑器细节体验表情面板、分隔线、列表编辑、代码块行号与导出高亮修复对使用 S3/WebDAV 自建同步的用户云端快照列表修复具有实际价值对插件/MCP 开发者新增的getPathByIDAPI 和succMap修复是直接的接口层收益对闪卡重度用户FSRS-5 是底层算法升级。变更日志同时提供 英文版 与 简体中文版可在官方发布渠道B3log 下载页、GitHub Releases获取对应安装包本文档目录 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），仅供参考
阅读完成 · 觉得有帮助？
