SiYuan v2.8.7 深度解析：插件系统首次落地、文件写入稳定性与增量刷新同步机制

SiYuan v2.8.7 深度解析：插件系统首次落地、文件写入稳定性与增量刷新同步机制

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

本篇针对 SiYuan（思源笔记）内核与应用层发布说明 v2.8.7 变更日志 展开技术解读，重点剖析该版本中"插件系统初步实现""文件系统写入重试""数据同步增量刷新"三大基础能力，并结合当前仓库源码核实集市包配置、内核 API 与 Petal 模块的实际承载结构。读完本文，你可以完整了解 v2.8.7 的体验改进清单、集市包开发者需要补齐的赞助/图标/国际化配置格式，以及后续插件体系在源码层面如何演化。

版本概述：一次"稳定与细节"双轨推进的迭代

v2.8.7 的总体定位可从概述中提炼为两条主线：

1. 细节体验打磨：折叠标题块后页面不再跳动、数据同步后不再整体刷新界面、WebSocket 重连后不刷新界面——所有改进都指向同一个目标，即"减少对当前工作状态的干扰"。
2. 稳定性加固：改进写入文件的稳定性，对因杀毒软件等外部原因导致文件被占用、写入失败的情况引入重试机制，缓解频繁出现的文件系统读写错误。

同时，该版本完成了对后续重要功能的两处奠基：

• 插件系统初步实现，供社区开发者早期接入，并计划在 v2.9.0 中正式发布；
• 间隔重复（闪卡）界面浮层可转换为页签，为后续复习工作流改造做准备。

文件系统：写入失败先重试、重试无效再退出内核

版本说明明确指出，此前存在一类导致内核直接退出的严重问题：某些外部进程（典型如杀毒软件）临时占用文件，使得内核在写入数据时失败。旧逻辑下写入失败即退出内核并弹出提示，会打断用户正在进行的编辑与保存流程。

v2.8.7 的修复策略是：

• 文件写入失败后先进入重试流程；
• 只有重试仍然失败时，才退出内核并提示用户。

这种"先自我修复、后升级报错"的层次化处理，显著降低了偶发占用造成的可用性事故。若你在升级前经常遇到文件系统读写错误，该版本应当能带来可感知的改善。从工程角度看，这一改进对应仓库中数据落盘相关的模型层（如 kernel/model/storage.go、kernel/model/tree.go 等文件负责的文档树序列化与事务写入流程）的容错逻辑，其核心价值是让"瞬时性的文件占用"不再与"永久性的磁盘故障"同等对待。

数据同步：从"整体刷新"到"按变更增量刷新"

v2.8.7 同步模块的核心体验改进是：数据同步完成后不再整体刷新整个界面，而是只刷新发生变更的部分。

此前同步结束后触发整页/整界面刷新，会带来明显的界面闪烁与滚动位置丢失，打断正在进行的阅读与编辑。改为增量刷新后：

• 只有被远程变更覆盖的文档、块与属性被重新渲染；
• 未变更区域的编辑器状态、滚动位置与选中内容得到保留；
• 视觉闪烁大幅减少。

与之配套的另一条相关改进是WebSocket 重连不再刷新界面（对应改进条目 "WebSocket 重连不再刷新界面"），说明该版本对"连接恢复"类事件同样采用了局部处理策略。仓库内核侧的消息推送由 kernel/model/push_reload.go 与 kernel/util/websocket.go 等模块承载，v2.8.7 的改动方向正是压缩这类推送事件对前端造成的"全量重载"冲击。

编辑器与交互：一批高频操作细节修正

v2.8.7 在块级编辑体验上集中修复和优化了大量细节点，值得逐条了解：

标题块与列表转换

• 折叠标题块后页面不再跳动：折叠/展开标题时避免滚动位置抖动，这是大纲类文档高频操作。
• 标题块开始前输入1.不再被转换为有序列表，避免在标题前误触列表转换。
• 在非空段落块开始前输入[]可转换为任务列表，补全了任务列表的触发边界。
• 修复在标题块开始前输入-、*和[]的解析异常（修复缺陷条目），与上面两条改进相互呼应，说明该版本对"块开始边界处的输入解析"做了系统性收敛。

空段落、选中与复制粘贴

• 对空段落使用F3进行"新建子文档名为"后，不再自动选中所有块，减少弹窗关闭后的误操作。
• 选择多个块复制后粘贴为纯文本时，改用换行分隔内容，使纯文本粘贴结果更贴近所见排版。
• "复制块超链接（Markdown）"的锚文本长度遵循编辑器设置"块引动态锚文本最大长度"，保证导出的 Markdown 链接与编辑器内预览保持一致。

PDF、题头图与移动端

• PDF 页签中点击损坏的超链接不再导致白屏，同时修复 PDF 页签中无法使用↑/↓键的问题。
• PDF 标注中包含换行时移除多余空格，提升标注文本的整洁度。
• 使用超链接设置题头图时支持包含空格的路径，覆盖了本地文件路径的常见形态。
• 改进移动端软键盘弹起后题头图的大小定位、在移动端显示空块提示、部分场景下移动端创建文档后不再自动跳转打开。

反链、属性、闪卡与编辑器加载

• 改进反链面板中列表上下文折叠逻辑、修复反链提及中键盘元素高亮不正确的问题。
• 属性对话框增加占位文案提示；自定义块属性支持更多符号（来源为社区 PR）。
• 改进制作闪卡后的动画与编辑器加载动画，扩大 AI Chat 输入框，扩大块标菜单中移动相关组合键的悬浮提示。

间隔重复：浮层转页签，复习与编辑并行

间隔重复（Spaced Repetition / 闪卡复习）是本版本体验提升的重要模块：

• 支持将间隔重复界面浮层转换为页签：此前间隔重复以浮层形式叠加，占用主界面且无法并行操作其他内容；转换为页签后，复习过程中可以随时查看、操作其他页签内容。
• 第二次按Alt+F时关闭间隔重复界面（此前第二次按键的行为不一致），让快捷键语义收敛为"开/关切换"。
• 间隔重复文档树过滤浮窗中显示计数，便于用户筛选待复习文档时预估复习量。

插件系统：Petal 模块与社区插件集市的起点

v2.8.7 最重要的一条底层铺垫是"初始化插件系统"。版本说明明确表述为：此版本初步实现插件系统，以便社区开发者能够开始进行早期接入，并计划于 v2.9.0 正式发布；同期还启动了"社区插件集市"。

对应在源码层面，仓库的插件能力最终沉淀为 kernel/plugin 目录下的完整体系，包括插件管理器、JSON-RPC 通信、沙箱与 WebSocket 通道等。该目录内的文件在后续版本中逐步形成了可运行的插件运行时，内核注册的插件相关 API 也可在 kernel/api/router.go 中看到，例如：

• /api/petal/loadPetals（加载花瓣/插件）与/api/petal/setPetalEnabled（启停插件，需要管理员角色）；
• /api/plugin/listLoadedPlugins、/api/plugin/getLoadedPlugin等插件查询接口；
• /api/plugin/rpc、/api/plugin/rpc/:name提供 HTTP 与 WebSocket 两种通道的 JSON-RPC 调用。

此外，"引入 Petal 模块"与"内核 API 支持加载插件"两条开发者条目，正是 v2.8.7 为插件系统打下的地基。需要特别说明的是，v2.8.7 仅完成了插件机制的初始化与早期接口预留，距离"开箱即用的插件生态"还有后续数个版本的迭代空间，这一点版本说明本身也以"初步实现"与"计划在 v2.9.0 中正式发布"做了明确界定。

社区集市：赞助、图标与国际化三项配置规范

v2.8.7 为社区集市中的各类扩展包（主题、图标、模板、挂件与插件）统一新增了三类配置项：

1. 赞助（Funding）：支持配置 Open Collective、Patreon、GitHub 以及自定义赞助链接。
2. 图标（Icon）：支持为扩展包配置展示图标。
3. 国际化（i18n）：支持为扩展包配置多语言文案。

集市包开发者需要同步更新自己包的配置，才能在新版集市中获得更完整的展示效果。当前仓库的内核解析侧保留了这套结构的承载实现，见 kernel/bazaar/package.go：

type Funding struct { OpenCollective string `json:"openCollective"` Patreon string `json:"patreon"` GitHub string `json:"github"` Custom []string `json:"custom"` // ... 其他字段 } type Package struct { // ... Funding *Funding `json:"funding"` // ... }

解析逻辑中getPreferredFunding的优先级顺序也值得关注：依次尝试Open Collective → Patreon → GitHub Sponsors → 自定义链接，找到第一个可用的赞助渠道后即采用，因此在同一包内配置多个渠道时，集市会按此顺序为用户呈现首选入口：

func getPreferredFunding(funding *Funding) string { if nil == funding { return "" } if v := normalizeFundingURL(funding.OpenCollective, "https://opencollective.com/"); "" != v { return v } if v := normalizeFundingURL(funding.Patreon, "https://www.patreon.com/"); "" != v { return v } if v := normalizeFundingURL(funding.GitHub, "https://github.com/sponsors/"); "" != v { return v } if 0 < len(funding.Custom) { v := funding.Custom[0] // ... } // ... }

对扩展包开发者而言，v2.8.7 引入的标准配置形态可概括为package.json中的三段声明（字段名与内核反序列化标签对应，即openCollective、patreon、github、custom、icon与多语言文案键）：

{ "name": "your-package", "funding": { "openCollective": "your-org", "patreon": "your-name", "github": ["your-github"], "custom": ["https://your-site.example/donate"] }, "icon": "icon.png", "i18n": { "en_US": "English display name", "zh_CN": "中文显示名称" } }

为帮助开发者快速对齐格式，官方在 v2.8.7 同期提供了集市包模板库，覆盖主题（theme）、图标（icon）、模板（template）、挂件（widget）与插件（plugin）五类示例模板（版本说明中以外部示例仓库形式给出，此处不展开外部链接），并补充了"集市包增加赞助设置 / 图标设置 / 国际化设置"三条开发者条目。

内核 API 与开发基建变更

v2.8.7 面向开发者开放/调整了若干 API：

/api/query/sql支持LIMIT子句

SQL 查询接口本次支持在查询语句中直接书写LIMIT子句，让客户端可以精确控制返回行数，而不再只能依赖服务端默认的行数上限。该接口注册于 kernel/api/router.go：

ginServer.Handle("POST", "/api/query/sql", model.CheckAuth, model.CheckAdminRole, model.CheckReadonly, SQL)

从路由声明可以看出其调用前提：需要管理员角色且仓库处于非只读状态，即query/sql是面向具备管理员权限调用方的只读数据查询通道。仓库 kernel/sql/block_query.go 中的 SQL 解析层对带LIMIT的语句提供了容纳与修正能力（例如在无分页条件时补充LIMIT、识别语句中已存在的limit子句等），为这类开放查询提供了统一约束。

listDocsByPath的sort参数

文件树相关 APIlistDocsByPath的参数sort得到改进，开发者可以更稳定地按指定排序方式枚举某路径下的文档列表，这一改动同样服务于集市、插件与第三方客户端的目录读取场景。

其他开发者侧变更

• 引入 Petal 模块：为插件系统提供内核侧基础设施，也是后续/api/petal/*与/api/plugin/*接口群的来源。
• 内核 API 支持加载插件：在初始化阶段打通"内核加载插件"的调用链。
• 释放 Electron 渲染窗口事件：降低桌面端（app/electron）渲染进程中的事件泄漏风险。
• 升级 Electron：桌面壳层（app/electron/main.js）随版本升级以获得 Chromium 内核的稳定性与安全修复。

AI 与图片等杂项能力

• 支持选择 GPT 模型gpt-4、gpt-4-32k与gpt-3.5-turbo：AI 对话功能的模型下拉选项得到扩充（说明该版本已进入 GPT-4 时代的多模型选择阶段）。
• 支持 AVIF 图片格式：编辑器与资源管理可识别 AVIF 图片，丰富图片资源的类型覆盖。
• 在华为手机上不再支持配置 OpenAI：属于特定设备环境下的功能约束调整（版本说明未展开原因，此处不做推断）。

缺陷修复速览

除上述条目外，v2.8.7 还修复了一批影响面较小的缺陷，可归类如下：

文档与下一步

• v2.8.7 在用户指南中新增了**"社区资源"与"术语表"**两个章节，帮助新用户理解社区扩展生态与基础术语。
• 版本说明明确将插件系统正式发布定档 v2.9.0，因此关注插件开发的读者，建议以 v2.8.7 作为配置/API 预研起点，及时跟进下一个正式版本。

综上所述，v2.8.7 的价值集中体现在三个层面：内核稳定性（写入重试、同步增量刷新）、体验一致性（间隔重复转页签、批量编辑细节修正）以及生态地基（插件系统初始化 + 集市包配置规范统一）。仓库内对应的 发布说明原始文档、集市包配置解析实现 与 内核 API 路由表 可作为继续深入的一手资料。

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