思源笔记 v2.9.5 深度解析面包屑交互重构、.sy 文件单行 JSON 存储与属性视图「表格化」【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan本篇文章基于思源笔记Siyuanv2.9.5 的官方发布说明繁体中文版另有简体中文版与英文版结合仓库当前源码对这一版本在面包屑组件、编辑器细节、.sy存储格式、属性视图Attribute View与内核网络 API 等方面的变化做逐项展开。读完你将理解为什么该版本值得升级、云同步为何在 v2.9.4 处设下版本门槛、.sy单行 JSON 配置项在前后端的完整生效链路以及插件开发者可用的新事件总线与/api/network/forwardProxy内核 API 的调用方式。版本概览细节打磨 数据格式兼容的一版官方概述将其定位为改进了面包屑和一些细节的版本同时明确了两点升级诉求修复了工作空间文件夹名称含非 ASCII 字符时无法导出 Data 的问题涉及所有使用非英文/非纯 ASCII 目录名的用户例如中文用户名路径下的工作空间云同步兼容门槛收紧由于旧版本存在可能导致云端数据损坏的问题v2.9.5 发布之后官方数据同步不再支持 v2.9.4 之前的旧版本。使用官方数据同步的用户必须升级到 v2.9.4 及以后版本。这一数据安全红线式声明属于服务端兼容策略的常见做法——客户端版本过旧时会与新版服务端协议不兼容强行同步可能引入脏数据因此上游以版本下限作为兜底保护。除上述两点外本版本变更集中在三块功能改进 15 项、缺陷修复 5 项、开发者能力 12 项其中开发者侧的重头戏是属性视图Attribute View在 v2.9.5 首次支持表格形态及其配套列类型。下文按此脉络逐一展开。面包屑Breadcrumb组件体验重塑v2.9.5 的多项改动围绕面包屑展开说明该版本在文档导航细节上做了集中打磨改进移动端面包屑issue #8623针对窄屏下的面包屑交互与布局进行了适配优化在面包屑右侧增加文档块标issue #8654用户可以直接从面包屑最右侧唤出文档级菜单进而对整篇文档执行只读/全宽等属性操作不必再回到文档树或编辑器顶部图标改进面包屑转义文本issue #8679处理了特殊字符如、、引号等在面包屑中显示被错误转义的问题动态计算面包屑高度issue #8674面包屑高度不再依赖固定值而是随内容动态测量避免文档标题过长时挤压/溢出编辑器区域。从当前源码看面包屑更多菜单的弹出逻辑集中在 app/src/protyle/breadcrumb/index.ts点击文档块标后会先通过fetchPost拉取文档统计信息response.data.stat中包含runeCount、wordCount、linkCount、imageCount、refCount、blockCount等随后追加只读的文档统计菜单项并向插件系统发出open-menu-breadcrumbmore事件详见后文开发者能力章节。这说明 v2.9.5 的面包屑并不是单纯的展示栏而是文档级操作与插件扩展的入口。编辑器与移动端的交互细节优化除面包屑外功能改进清单还覆盖了导出预览、移动端生命周期、集市、同步与关系图等模块变更点issue说明导出预览模式下页签切换大纲跟随切换#8669导出预览中切换页签时右侧大纲不再滞留旧页签内容而是跟随当前预览文档联动移动端「退出应用」时保存文档浏览状态#8670记录退出前正在浏览的文档下次启动恢复浏览位置改进集市界面布局对齐#8671集市Marketplace卡片/列表的对齐细节修正改进云端数据同步报错文案#8675同步失败时的提示信息更明确便于判断是网络、账号还是版本原因改进「关系图」设置界面#8676关系图Graph View的设置项布局与文案调整停用账号前需输入用户名和密码进行校验#8680账号停用属于高风险操作强制二次身份确认防止误操作或越权改进设置界面#8685通用设置界面布局细节优化反链链接面板颜色不再受提及折叠状态影响#8688反链面板Backlink中链接高亮颜色与提及/折叠状态解耦避免状态切换导致颜色跳变更新移动端缩进/反向缩进图标#8698工具栏图标样式刷新改进桌面端创建工作空间交互#8700首次启动/切换工作空间的创建流程更顺畅其中关系图与反链分别对应内核中的 kernel/model/graph.go 与 kernel/model/backlink.go 数据服务这类纯前端 UI 改动在桌面端与移动端代码中各自维护实现属于典型的端侧体验收敛型发布。.sy文件单行 JSON 存储.sy是思源文档在磁盘上的持久化格式本质是一个 JSON 结构的文档树。历史上思源默认将其格式化多行缩进存储便于人工阅读排查。v2.9.5 新增能力issue #8712支持以单行 JSON 格式保存.sy文件同时覆盖属性视图的.json文件。这是文件系统层面的一个可配置行为而非强制切换。配置项与前后端生效链路前端设置项位于「设置 → 文件树」中开关绑定的配置键为fileTree.useSingleLineSave见 app/src/config/tabs/fileTab.ts该键的类型声明在 app/src/types/config.d.ts注释明确写着Whether to save the content of the .sy file as a single-line JSON object内核侧配置结构体字段定义于 kernel/conf/filetree.goJSON 键同样为useSingleLineSave使用单行保存文档 .sy 和属性视图 .json配置读取时kernel/model/conf.go 会把该值同步到全局变量util.UseSingleLineSave用户在设置界面保存配置后kernel/api/setting.go 同样会刷新该全局变量保证无需重启立即生效实际写入时kernel/model/export.go文档树渲染落盘与 kernel/model/import.go导入/转存都会判断util.UseSingleLineSave为false时对渲染结果做缩进美化为true时直接以紧凑的单行 JSON 落盘。关于.sy的文件级格式约定可进一步参考仓库中的 SY-FORMAT 说明中文见 SY-FORMAT.zh-CN.md。单行格式的价值与取舍从工程角度看单行 JSON 存储主要有三类收益显著减小文件体积去掉换行与缩进空格后包含大量子块的文档磁盘占用明显下降云同步与本地备份的数据量随之减少利于版本控制与差异对比单行格式下每个文档对应一条紧凑记录配合 Git 等工具做内容级 diff 时更稳定不会因缩进变动产生大量噪声差异便于脚本与程序化处理对 JSON 解析器更友好适合二次开发工具批量读取。代价是人类直接阅读与手改.sy文件的体验下降。因此思源将其做成一个可开关的配置项而不是默认强制。若更看重可读性与调试便利保持默认的多行缩进格式即可。顺带一提与该配置相邻的largeFileWarningSize大文件警告阈值默认 8MB见 kernel/conf/filetree.go用于在编辑超大文档/超大属性视图时给出性能提示两者共同服务于大规模文档场景的存储与编辑体验。行级元素合并策略调整issue #8713 描述了一项编辑器底层行为变更不再自动合并相邻换行的行级元素。在思源的块级编辑器基于 Protyle/WYSIWYG中同一段落内换行产生的相邻行级元素行内节点过去会被编辑器自动合并v2.9.5 起这一自动合并被移除。其意义在于当两行各自带有不同的行级属性例如字体、颜色、行内公式/代码标记或者用户通过换行有意分隔渲染内容时编辑器将保留这两行元素的独立性不再静默改写结构从而保证复制、导出与排版结果符合用户原始输入。这属于少干预、保原样的编辑器策略调整对追求精确排版的长文档用户更为友好。缺陷修复盘点与实现位置v2.9.5 修复的 5 个缺陷覆盖了导出、表格、复制与排版四大场景修复项issue影响面工作空间文件夹名含非 ASCII 字符时无法导出 Data#8678中文/日文等多字节路径下的「导出 Data」失败表格单元格内三击全选后无法修改字体外观#8703表格中三击选中整格文本后字号/字体颜色等外观修改失效HTML 块相关复制问题#8706HTML 块在复制/粘贴场景下的内容异常列表项带特定自定义属性值时复制内容不正确#8707列表项携带特定custom-*属性时复制结果错乱标题块父级构造列表项后「优化排版」解析异常#8709将标题块转换为列表子项后执行优化排版出现解析错误其中#8678 是本次最重要的缺陷修复导出 Data 的入口是内核 API/api/export/exportData路由注册见 kernel/api/router.go处理函数位于 kernel/api/export.go该功能会把整个工作空间打包为数据备份。当工作空间绝对路径中混入非 ASCII 字符如用户名含中文时打包/解包环节存在路径处理缺陷导致失败。该问题修复意味着以中文等非英文目录名创建工作空间的用户在 v2.9.5 之后可以正常执行「设置 → 导出 → 导出 Data」的完整数据备份流程。其余复制类缺陷集中在剪贴板与块属性序列化逻辑内核侧可参考 kernel/util/clipboard.go 与块属性处理模块 kernel/treenode优化排版则与 kernel/model/format.go 的排版重排逻辑相关。开发者能力一属性视图Attribute View迈向表格化v2.9.5 的开发者清单几乎全部围绕属性视图展开标志着这一面向结构化知识管理的能力开始成熟编辑器支持属性视图 - 表格issue #7536编辑器内首次原生支持以表格形态渲染属性视图属性视图列排序issue #8663支持对列做自定义排序属性视图添加数字类型列issue #8690新增number列类型可存储并参与排序/计算属性视图添加文本类型列issue #8693新增text列类型属性视图添加选择类型列issue #8694新增select列类型配合下拉选项完成枚举值录入属性视图支持过滤、属性和排序面板中的项目排序issue #8691三个配置面板中的项目排列顺序可调块数据同步至属性视图issue #8696块内容/块引用可向属性视图行同步为块 ↔ 数据库行联动打下基础。块数据同步至属性视图意味着属性视图不只是独立的二维表它能够感知文档树中的真实块block——这是属性视图与普通表格的本质差异也为后续基于属性视图构建看板、画廊等视图形态埋下伏笔。从仓库现状看属性视图相关的内核实现非常庞大数据层与表格/画廊/看板各视图布局实现在 kernel/av如 av.go、layout_table.go、layout_gallery.go、layout_kanban.go模型层在 kernel/model/attribute_view.go 及同目录attribute_view_*.go系列SQL 查询/缓存层在 kernel/sql 下的av*.go文件内核 API 入口则在 kernel/api/av.go。可以说 v2.9.5 的表格列类型与排序只是起点如今已成长为支持数字/文本/选择/日期/资源等多种列类型、多视图形态的大型子系统。开发者能力二插件事件总线新增open-menu-breadcrumbmore插件系统在本版本获得了一个新事件类型open-menu-breadcrumbmoreissue #8666。事件类型名收录在事件总线类型联合中见 app/src/types/index.d.ts。实际触发位置在面包屑更多菜单弹出处app/src/protyle/breadcrumb/index.tsif (protyle?.app?.plugins) { emitOpenMenu({ plugins: protyle.app.plugins, type: open-menu-breadcrumbmore, detail: { protyle, data: response.data.stat, // 文档统计字数、块数、引用数等 }, separatorPosition: top, }); }插件监听该事件后即可在面包屑右侧的文档菜单中注入自己的菜单项detail.data携带了当前文档的统计信息runeCount、wordCount、blockCount、linkCount等detail.protyle则给出编辑器实例上下文。这使得插件无需再通过 DOM hack 就能扩展文档级操作入口。同批还补充了bind this事件总线示例issue #8668当插件回调中需要访问插件实例如调用this.log、this.loadData时事件监听函数应使用箭头函数或显式绑定this避免在事件回调的独立作用域中丢失插件上下文——这属于典型的 JSthis绑定陷阱官方通过示例帮助插件作者规避。开发者能力三内核 API/api/network/forwardProxy本版本新增了一个面向管理员的服务端网络转发 APIPOST /api/network/forwardProxyissue #8724。路由注册于 kernel/api/router.go并挂载了CheckAuth登录校验与CheckAdminRole管理员角色校验实现位于 kernel/api/network.go 起的forwardProxy函数。请求参数参数是否必填默认值说明url是无目标地址仅允许http/https协议非法地址返回错误码 1method否POSTHTTP 方法服务端会转为大写timeout否7000毫秒请求超时小于 1 时回退到默认 7000msredirect否true是否跟随重定向传false时使用不跟随重定向策略headers否无请求头数组元素为键值对对象逐项设置contentType否application/json请求Content-TypepayloadEncoding否json载荷编码json、base64/base64-std、base64-url、base32/base32-std、base32-hex、hex、textpayload按需无请求体二进制类编码如base64会先解码再发送responseEncoding否text响应体编码取值同上用于将响应内容回传为文本实现细节kernel/api/network.go函数先解析并校验urlscheme非http/https时直接返回错误码 2随后按method、timeout、redirect构建带超时与重定向策略的客户端根据payloadEncoding对载荷做对应解码错误码 3~7 分别对应 base64-std、base64-url、base32-std、base32-hex、hex 解码失败text以外的编码分支通过request.SetBody写入解码后的二进制内容最后request.Send(method, destURL)发起请求请求失败返回错误码 8读取响应失败返回错误码 9。responseEncoding用于把响应字节编码回文本含各 base32/base64/hex 变体便于上层拿到可直接落库或展示的结果。与其他代理 API 的定位差异仓库中已存在POST /api/network/proxyHTTP 代理与GET /ws/network/proxyWebSocket 代理见 kernel/api/router.go。相比之下forwardProxy是一次性的服务端请求转发它不建立长连接而是让内核作为一个受控 HTTP 客户端代为向第三方 URL 发请求并把响应回传。对于桌面端渲染进程或浏览器中受同源策略限制、需要绕过跨域约束的场景插件与前端可以借助该 API 经由本地内核完成对第三方服务的调用。因为该接口需要管理员角色实践中应仅将其暴露给可信调用方。升级建议与延伸阅读务必升级如果正在使用官方数据同步请至少升级到 v2.9.4含以上版本否则将因版本兼容策略无法继续同步注意工作空间路径如果你的数据目录/工作空间路径含中文等多字节字符且此前导出 Data 失败v2.9.5 已修复该问题建议升级后完整执行一次「导出 Data」验证数据备份能力关注.sy存储格式启用单行保存 .sy后磁盘占用与同步体积会下降但文件可读性降低按需开启即可该配置保存在设置中的文件树分组下配置键fileTree.useSingleLineSave。本版本三种语言的完整发布说明均可直接查阅v2.9.5.md英文、v2.9.5_zh_CN.md简体中文、v2.9.5_zh_CHT.md繁体中文仓库根目录的 CHANGELOG.md 汇总了全部历史版本记录。若希望深入了解内核与编辑器实现可从 AGENTS.md 入手概览工程结构再按上文给出的文件路径逐模块深入。【免费下载链接】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），仅供参考