思源筆記 v3.5.3 深度解析拖放性能優(yōu)化、導(dǎo)出增強(qiáng)與新增批量塊內(nèi)容內(nèi)核 API【免費(fèi)下載鏈接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 開源、隱私優(yōu)先、自托管的知識(shí)工作空間讓人與智能體在此協(xié)作項(xiàng)目地址: https://gitcode.com/GitHub_Trending/si/siyuan本篇技術(shù)指南圍繞思源筆記SiYuanv3.5.3 版本的官方變更記錄v3.5.3_zh_CN.md展開逐一拆解該版本在性能、導(dǎo)出、同步、桌面端體驗(yàn)四個(gè)方向上的改進(jìn)項(xiàng)、缺陷修復(fù)與開發(fā)者接口變更。讀者可以通過本文掌握每個(gè)變更背后的內(nèi)核實(shí)現(xiàn)位置與調(diào)用鏈從而理解思源在改進(jìn)細(xì)節(jié)這類小版本迭代中的實(shí)際工程取舍并可直接對(duì)照源碼驗(yàn)證。版本概述與變更范圍v3.5.3 的官方定位是此版本改進(jìn)了一些細(xì)節(jié)但從變更記錄看它實(shí)際覆蓋了編輯體驗(yàn)、數(shù)據(jù)同步、資源管理、導(dǎo)出鏈路、桌面端打包與開發(fā)者 API 六個(gè)領(lǐng)域共約 27 項(xiàng)功能改進(jìn)、4 項(xiàng)缺陷修復(fù)和 1 項(xiàng)新增內(nèi)核 API。該版本同時(shí)發(fā)布簡(jiǎn)體中文、繁體中文與英文三份變更記錄本倉(cāng)庫(kù)中對(duì)應(yīng)文件為 v3.5.3_zh_CN.md、v3.5.3_zh_CHT.md 與 v3.5.3.md。下文按主題分組解讀全部變更項(xiàng)并在每節(jié)給出對(duì)應(yīng)的倉(cāng)庫(kù)源碼證據(jù)。編輯體驗(yàn)與界面交互改進(jìn)文檔樹拖放性能與動(dòng)態(tài)加載本版本改進(jìn)文檔樹的拖放drag drop性能并支持剪切塊后動(dòng)態(tài)加載文檔issue 16767。后者意味著當(dāng)塊被剪切到其他文檔時(shí)目標(biāo)文檔不再要求整體預(yù)加載而是按需動(dòng)態(tài)裝載文檔樹節(jié)點(diǎn)這與內(nèi)核側(cè)loadTreeByBlockIDInBox的按需加載模型一致——在批量導(dǎo)出、剪切粘貼等場(chǎng)景中文檔樹均以塊 ID 為單位按需讀取見下文 API 一節(jié)的源碼分析。撤銷恢復(fù)光標(biāo)位置與 ChatGPT 粘貼體驗(yàn)撤銷應(yīng)在按回車后恢復(fù)光標(biāo)位置issue 16595在編輯器中觸發(fā)回車后執(zhí)行撤銷光標(biāo)會(huì)回到按下回車前的位置避免撤銷后光標(biāo)漂移到文檔末尾或錯(cuò)誤行。改進(jìn)從 ChatGPT 應(yīng)用復(fù)制文本的體驗(yàn)issue 14819針對(duì) AI 對(duì)話應(yīng)用復(fù)制出的富文本/帶標(biāo)記內(nèi)容改進(jìn)粘貼時(shí)的解析與清洗減少多余格式殘留。折疊標(biāo)題與列表編輯細(xì)節(jié)改進(jìn)列表編輯中折疊標(biāo)題的處理issue 16769折疊標(biāo)題heading 折疊狀態(tài)在列表項(xiàng)編輯過程中不再被錯(cuò)誤展開或丟失。改進(jìn)在提示、引用和列表項(xiàng)中折疊標(biāo)題指示器的顯示issue 16805折疊標(biāo)題的指示器折疊箭頭在提示塊hint block、引用和列表項(xiàng)等嵌套場(chǎng)景下的顯示位置與層級(jí)得到修正。改善可折疊列表塊中 Mermaid 塊的渲染issue 16802Mermaid 圖表在折疊列表塊內(nèi)的渲染時(shí)序被調(diào)整避免折疊狀態(tài)下圖表空白或加載失敗。改進(jìn)提示塊圖標(biāo)的交互issue 16758與提示塊、數(shù)據(jù)庫(kù)中修改表情不再更新常用表情列表issue 16746前者優(yōu)化了提示塊圖標(biāo)的點(diǎn)擊/懸停響應(yīng)后者屬于行為修正——此前在提示塊或數(shù)據(jù)庫(kù)屬性中改動(dòng)表情會(huì)污染全局常用表情列表v3.5.3 起此類改動(dòng)不再寫入常用表情記錄。搜索結(jié)果定位與表格復(fù)制改進(jìn)搜索結(jié)果打開編輯器時(shí)的定位issue 16739從搜索結(jié)果跳轉(zhuǎn)打開編輯器時(shí)滾動(dòng)定位更精確目標(biāo)塊能穩(wěn)定進(jìn)入視口。改進(jìn)表格復(fù)制PR 16783從渲染表格復(fù)制到外部應(yīng)用時(shí)單元格分隔與換行規(guī)則更貼近表格語(yǔ)義。只讀模式與數(shù)據(jù)庫(kù)交互修正修復(fù)只讀模式下點(diǎn)擊文檔導(dǎo)致錯(cuò)誤issue 16762只讀角色ReadOnlyRole下點(diǎn)擊文檔不再觸發(fā)異常。內(nèi)核側(cè)存在完整的只讀上下文判定邏輯model.IsReadOnlyRoleContext與發(fā)布訪問過濾filterBlockKramdownsByPublishAccess此修復(fù)使前端在只讀上下文中跳過寫路徑操作。修復(fù)分組視圖下數(shù)據(jù)庫(kù)單元格拖放填充行為異常issue 16760數(shù)據(jù)庫(kù)分組視圖layout_gallery、layout_kanban、layout_table等分組布局中單元格拖放填充的取值與落點(diǎn)校驗(yàn)得到修正相關(guān)布局實(shí)現(xiàn)位于 kernel/av/layout_gallery.go、kernel/av/layout_kanban.go 與 kernel/av/layout_table.go。改進(jìn)數(shù)據(jù)庫(kù)資源字段菜單中圖片點(diǎn)擊的行為PR 16671資源字段菜單內(nèi)點(diǎn)擊圖片時(shí)優(yōu)先打開圖片預(yù)覽而非誤觸發(fā)其他操作。資源、導(dǎo)入與導(dǎo)出鏈路增強(qiáng)支持將代碼塊導(dǎo)出為文件PR 16774這是本版本較有工程價(jià)值的一項(xiàng)能力代碼塊現(xiàn)在可以直接導(dǎo)出為.txt文件而不再需要復(fù)制代碼再手動(dòng)新建文件。內(nèi)核側(cè)實(shí)現(xiàn)路徑清晰API 入口為 kernel/api/export.go 中的exportCodeBlock接收必填參數(shù)id塊 ID內(nèi)部調(diào)用model.ExportCodeBlock(id)。核心邏輯位于 kernel/model/export.gonode : treenode.GetNodeInTree(tree, blockID) if ast.NodeCodeBlock ! node.Type { return errors.New(not a code block) } code : node.ChildByType(ast.NodeCodeBlockCode) if nil code { return errors.New(code block has no code node) } name : tree.Root.IALAttr(title) - util.CurrentTimeSecondsStr() .txt exportFolder : filepath.Join(util.TempDir, export) // 加密筆記本的導(dǎo)出歸入 boxID 子目錄 if IsEncryptedBox(tree.Box) { exportFolder filepath.Join(exportFolder, tree.Box) }從源碼可以確認(rèn)三個(gè)行為細(xì)節(jié)一是僅塊類型為NodeCodeBlock時(shí)才允許導(dǎo)出否則返回not a code block錯(cuò)誤二是導(dǎo)出文件名由文檔標(biāo)題加時(shí)間戳組成三是導(dǎo)出文件先寫入TempDir/export臨時(shí)目錄加密筆記本IsEncryptedBox還會(huì)按boxID分子目錄并通過registerManagedEncryptedExport注冊(cè)托管 token 后才能被下載/export/...路徑這保證了加密筆記本的明文代碼不會(huì)繞過鎖定狀態(tài)被讀取。優(yōu)化導(dǎo)出為 Word .docx 時(shí)對(duì)資源的處理issue 15253導(dǎo)出 Word 文檔時(shí)對(duì)資源圖片、附件的處理得到優(yōu)化。內(nèi)核導(dǎo)出鏈路中ExportMarkdownHTMLkernel/model/export.go在docxtrue時(shí)會(huì)調(diào)用getAssetsLinkDests(tree.Root, docx)收集資源鏈接目標(biāo)再經(jīng)由 pandoc 轉(zhuǎn)換為 docxpandoc : exec.Command(Conf.Export.PandocBin, args...)。v3.5.3 的優(yōu)化主要落在資源鏈接目標(biāo)assetLinkDest的判定與復(fù)制環(huán)節(jié)減少 docx 導(dǎo)出后資源缺失或路徑錯(cuò)亂的情況。改進(jìn)導(dǎo)出預(yù)覽模式issue 16732導(dǎo)出預(yù)覽export preview模式下的渲染細(xì)節(jié)得到修正預(yù)覽內(nèi)容與實(shí)際導(dǎo)出文件的一致性更高。改進(jìn) PDF 矩形注釋截圖的旋轉(zhuǎn)處理PR 16714PDF 矩形注釋highlight/rect annotation生成截圖時(shí)對(duì)旋轉(zhuǎn)頁(yè)面Rotate 屬性非 0的坐標(biāo)變換做了修正避免旋轉(zhuǎn)頁(yè)面上的注釋截圖方向錯(cuò)誤。PDF 相關(guān)處理邏輯位于 kernel/model/pdf.go。改進(jìn) PlantUML 的 PDF 導(dǎo)出issue 16776PlantUML 圖在 PDF 導(dǎo)出中的渲染兼容性得到修正避免圖塊在 PDF 中丟失或排版錯(cuò)亂。改進(jìn) HTML 塊解析issue 16778HTML 塊的解析規(guī)則做了收緊與修正提升粘貼/導(dǎo)入 HTML 內(nèi)容時(shí)的結(jié)構(gòu)化轉(zhuǎn)換質(zhì)量相關(guān)解析與 Lute 引擎聯(lián)動(dòng)kernel/model與kernel/util/lute.go中維護(hù)了解析參數(shù)。數(shù)據(jù)同步、代碼片段與存儲(chǔ)維護(hù)提升 S3 數(shù)據(jù)同步與 RustFS 的兼容性issue 16742S3 協(xié)議數(shù)據(jù)同步在與 RustFS 類對(duì)象存儲(chǔ)如自建 Rust 實(shí)現(xiàn)的 S3 兼容存儲(chǔ)對(duì)接時(shí)的兼容性得到提升主要涉及分片上傳、ETag 校驗(yàn)等協(xié)議細(xì)節(jié)使更多自托管對(duì)象存儲(chǔ)后端可以穩(wěn)定使用思源的 S3 同步方案。該能力屬于 kernel/conf/sync.go 與 kernel/model/sync.go 配置與執(zhí)行鏈路的一部分。改進(jìn)移動(dòng)端數(shù)據(jù)同步后資源數(shù)據(jù)索引的更新issue 16747移動(dòng)端在數(shù)據(jù)同步完成后資源數(shù)據(jù)索引asset content 索引的更新時(shí)序被修正避免同步后搜索/引用資源內(nèi)容時(shí)索引滯后。數(shù)據(jù)同步后自動(dòng)應(yīng)用代碼片段issue 16736此前用戶修改代碼片段JS/CSS snippet后需要手動(dòng)重啟或重載才能生效v3.5.3 起數(shù)據(jù)同步完成后會(huì)自動(dòng)重新加載并應(yīng)用代碼片段。內(nèi)核側(cè)片段的管理入口在 kernel/model/snippet.goLoadSnippets()通過snippetsLock互斥鎖保護(hù)從util.SnippetsPath/conf.json讀取片段配置type支持css/js并統(tǒng)計(jì)啟停數(shù)量同步完成后觸發(fā)片段重新加載即是對(duì)該文件讀取鏈路的再次調(diào)用使conf.json中enabled的 CSS/JS 片段無(wú)需手動(dòng)刷新即可生效。支持清理臨時(shí)文件issue 16745本版本新增清理臨時(shí)文件能力可一鍵回收運(yùn)行過程中在臨時(shí)目錄里累積的導(dǎo)出、導(dǎo)入、轉(zhuǎn)換等中間產(chǎn)物。內(nèi)核實(shí)現(xiàn)API 路由POST /api/system/clearTempFileskernel/api/router.go需要登錄與管理員角色model.CheckAuth、model.CheckAdminRole、model.CheckReadonly。入口處理kernel/api/system.go 的clearTempFiles直接委托model.ClearTempFiles()。清理范圍kernel/model/box.go 中的ClearTempFiles依次清理util.TempDir下的bazaar、export、import、convert、os、base64、install、thumbnails、repo等子目錄并統(tǒng)計(jì)刪除的文件數(shù)量與釋放字節(jié)數(shù)通過util.PushMsg/util.PushUpdateMsg向前端推送進(jìn)度與結(jié)果結(jié)果文案使用humanize.BytesCustomCeil格式化容量。這意味著導(dǎo)出文檔、導(dǎo)入數(shù)據(jù)、集市下載、縮略圖生成等活動(dòng)遺留的中間文件都可以通過該功能安全回收。桌面端與發(fā)布相關(guān)改進(jìn)Windows 端安裝后自動(dòng)清理 siyuan-updaterissue 16733Windows 桌面版安裝完成后會(huì)自動(dòng)刪除\%LOCALAPPDATA%\siyuan-updater\文件夾清理升級(jí)器殘留的舊版本文件避免升級(jí)器目錄持續(xù)膨脹。改進(jìn)桌面自動(dòng)更新PR 16764桌面端自動(dòng)更新流程得到改進(jìn)包括更新包下載、校驗(yàn)與安裝步驟的穩(wěn)健性減少更新失敗后的半更新狀態(tài)。桌面端打包與簽名腳本見 app/scripts/afterPack.js 與 app/scripts/signDevElectron.js。優(yōu)化錯(cuò)誤窗口信息布局PR 16735錯(cuò)誤彈窗的信息布局被重新組織堆棧信息與錯(cuò)誤上下文更易讀便于排查。發(fā)布服務(wù)關(guān)閉時(shí)自動(dòng)關(guān)閉瀏覽器頁(yè)面PR 16804當(dāng)思源發(fā)布服務(wù)publish被關(guān)閉時(shí)若此前通過瀏覽器打開了發(fā)布頁(yè)面相關(guān)瀏覽器頁(yè)面會(huì)自動(dòng)關(guān)閉避免殘留失效頁(yè)面。發(fā)布訪問控制的過濾邏輯與只讀上下文判定可參見 kernel/model/publish_access.go。缺陷修復(fù)匯總v3.5.3 共修復(fù) 4 項(xiàng)缺陷缺陷影響場(chǎng)景說明搜索時(shí)文檔標(biāo)題顯示不正確issue 16741搜索結(jié)果列表標(biāo)題高亮/截?cái)噙壿嬓拚謴?fù)正確標(biāo)題文本分組視圖下數(shù)據(jù)庫(kù)單元格拖放填充行為異常issue 16760數(shù)據(jù)庫(kù)分組視圖分組后的單元格拖放填充取值與落點(diǎn)校驗(yàn)修正只讀模式下點(diǎn)擊文檔導(dǎo)致錯(cuò)誤issue 16762只讀角色/發(fā)布上下文只讀上下文下點(diǎn)擊文檔不再觸發(fā)異常路徑多工作區(qū)訪問鑒權(quán)錯(cuò)誤issue 16786多工作區(qū)切換不同工作區(qū)之間的訪問令牌/鑒權(quán)狀態(tài)隔離修正其中只讀模式與多工作區(qū)鑒權(quán)兩項(xiàng)與內(nèi)核的會(huì)話與權(quán)限體系相關(guān)只讀判定貫穿kernel/model的發(fā)布訪問過濾鑒權(quán)中間件則統(tǒng)一注冊(cè)在 kernel/api/router.go 的model.CheckAuth、model.CheckAdminRole等處理器上。開發(fā)者新增內(nèi)核 API/api/block/getBlockKramdowns作為面向開發(fā)者的一項(xiàng)實(shí)質(zhì)增量v3.5.3 新增了批量獲取塊內(nèi)容的內(nèi)核 APIPR 16751可一次請(qǐng)求返回多個(gè)塊的 Kramdown 內(nèi)容適用于插件、腳本或集成方批量讀取文檔塊內(nèi)容避免對(duì)單個(gè)塊逐一調(diào)用既有接口。路由注冊(cè)與權(quán)限路由注冊(cè)于 kernel/api/router.goginServer.Handle(POST, /api/block/getBlockKramdowns, model.CheckAuth, model.CheckAdminRole, getBlockKramdowns)與單塊接口/api/block/getBlockKramdown并列同樣要求已登錄且具備管理員角色。請(qǐng)求參數(shù)與實(shí)現(xiàn)細(xì)節(jié)實(shí)現(xiàn)位于 kernel/api/block.go 的getBlockKramdowns核心處理邏輯如下ids必填字符串?dāng)?shù)組目標(biāo)塊 ID 列表。源碼會(huì)對(duì)每個(gè) ID 做格式校驗(yàn)util.InvalidIDPattern跳過無(wú)效 ID。mode可選字符串導(dǎo)出模式默認(rèn)md僅接受兩個(gè)取值mdMarkdown 標(biāo)記符模式使用標(biāo)記符marker導(dǎo)出內(nèi)部走treenode.ExportNodeStdMd并開啟SetPreventEncodeLinkSpace(true)鏈接/圖片 URL 中的空格不再被編碼對(duì)應(yīng) issue 15611 的既有行為textmark文本標(biāo)記模式使用 span 標(biāo)簽導(dǎo)出內(nèi)部走render.NewFormatRenderer渲染。傳入其他值返回code -1、msg Invalid mode。加密筆記本參數(shù)通過encryptedNotebookFromArg(arg)解析boxID當(dāng)存在boxID時(shí)改走model.GetBlockKramdownsInBox保證加密筆記本的讀取被正確路由到其 box 上下文。返回結(jié)構(gòu)為{ code: 0, data: { blockID: kramdown 內(nèi)容, ... } }在只讀角色上下文model.IsReadOnlyRoleContext下還會(huì)通過filterBlockKramdownsByPublishAccess按發(fā)布訪問控制過濾掉無(wú)權(quán)讀取的塊防止通過該 API 繞過發(fā)布權(quán)限。底層批量讀取模型內(nèi)核模型層實(shí)現(xiàn)位于 kernel/model/block.gofunc GetBlockKramdowns(ids []string, mode string) (ret map[string]string) { return GetBlockKramdownsInBox(ids, mode, ) } func GetBlockKramdownsInBox(ids []string, mode, boxID string) (ret map[string]string) { ret make(map[string]string, len(ids)) luteEngine : NewLute() for _, id : range ids { // 節(jié)點(diǎn)會(huì)被移走tree 不能共享需重新加載 tree, err : loadTreeByBlockIDInBox(id, boxID) if err ! nil { continue } ret[id] getBlockKramdown0(tree, id, mode, luteEngine) } return }源碼注釋明確說明了批量實(shí)現(xiàn)的關(guān)鍵約束由于塊可能被移動(dòng)剪切/粘貼每個(gè) ID 都必須重新加載所在文檔樹loadTreeByBlockIDInBox不能共享同一個(gè)tree實(shí)例。getBlockKramdown0會(huì)先addBlockIALNodes補(bǔ)充塊屬性列表IAL節(jié)點(diǎn)再把目標(biāo)塊與其 IAL 包裝進(jìn)一個(gè)臨時(shí)NodeDocument根節(jié)點(diǎn)后執(zhí)行導(dǎo)出因此返回內(nèi)容包含塊的 IAL 屬性信息適合需要讀取塊屬性如自定義屬性、樣式標(biāo)記的集成場(chǎng)景。調(diào)用示例curl -X POST http://127.0.0.1:6806/api/block/getBlockKramdowns \ -H Authorization: Token 你的API令牌 \ -H Content-Type: application/json \ -d { ids: [20240101120000-abcdefg, 20240101120001-hijklmn], mode: md }響應(yīng)示例{ code: 0, msg: , data: { 20240101120000-abcdefg: 這是一段段落文本。\n{: id\20240101120000-abcdefg\}, 20240101120001-hijklmn: go\nfmt.Println(\hello\)\n\n{: id\20240101120001-hijklmn\} } }上述響應(yīng)中的 ID 格式與 IAL 尾部標(biāo)記僅為示意實(shí)際內(nèi)容以目標(biāo)文檔為準(zhǔn)。下載與升級(jí)v3.5.3 隨版本發(fā)布提供各平臺(tái)安裝包。升級(jí)后建議重點(diǎn)關(guān)注以下可驗(yàn)證行為在設(shè)置中體驗(yàn)新增的清理臨時(shí)文件入口對(duì)應(yīng)/api/system/clearTempFiles對(duì)代碼塊執(zhí)行導(dǎo)出為文件以及通過開發(fā)者工具或腳本調(diào)用/api/block/getBlockKramdowns驗(yàn)證批量讀取。倉(cāng)庫(kù)內(nèi)還保留了該版本其余語(yǔ)言與后續(xù)版本的變更記錄見 app/changelogs 目錄可作為版本演進(jìn)的對(duì)照參考?！久赓M(fèi)下載鏈接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 開源、隱私優(yōu)先、自托管的知識(shí)工作空間讓人與智能體在此協(xié)作項(xiàng)目地址: https://gitcode.com/GitHub_Trending/si/siyuan創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考