SiYuan v2.10.3 版本深度解析：資源文件內容搜索修復、EPUB 解析優化與插件 API 能力補全

SiYuan v2.10.3 版本深度解析資源文件內容搜索修復、EPUB 解析優化與插件 API 能力補全【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuanv2.10.3 是思源筆記SiYuan在 v2.8.4v2.12.8 迭代窗口中的一個重點維護版本核心工作聚焦在「資源文件內容搜索」的缺陷修復與 EPUB 資源文件解析優化兩條主線同時完成了面向桌面端/移動端的一批交互細節改進並為插件開發者補齊了openWindow、command.globalCallback、鑑權token查詢參數等能力。閱讀本文後你將完整掌握該版本的改進全景、資源內容搜索背後的內核解析器設計以及各項修復對應的代碼層原理便於在實際使用或二次開發中準確定位與驗證。版本概述一次聚焦「資源內容索引」的維護迭代依照 v2.10.3_zh_CHT.md 的說明該版本主要修復了一些資源文件內容搜索相關的問題並優化了 EPUB 資源文件解析。需要特別說明的是「搜索資源文件內容」這項特性屬於付費會員功能在當時處於早鳥價階段僅限會員使用。在官方變更記錄中本版本合計包含 20 項改進功能含前後端與移動端、7 項缺陷修復與 4 項開發者相關變更涵蓋範圍從 PDF/EPUB 解析、浮層與停靠欄交互、網絡圖片下載一直到插件 API 與內核 HTTP 接口的行為規範。資源文件內容搜索從「支持」到「穩定可用」v2.10.3 對資源文件內容搜索的關注並非從零開始建設而是對既有索引管線做收尾修復與體驗打磨。理解這些修復需要先了解該功能在內核側的實現結構。內核側的解析器註冊表資源內容搜索的底層位於 kernel/model/asset_content.go。NewAssetsSearcher以「擴展名 → 解析器」的映射表構建解析器註冊表將不同類型的資源文件分派給對應的AssetParser實現純文本類.txt、.md、.json、.html、.xml、各類源代碼與配置文件等數十種統一交由TxtAssetParser處理Office 三件套分別使用DocxAssetParser、PptxAssetParser、XlsxAssetParserPDF 使用基於go-pdfium的PdfAssetParser見 asset_content.go 起並行頁級文本抽取的 worker 設計EPUB 則由EpubAssetParser承接。其中還有兩個硬性限制常量值得注意純文本類單文件最大解析 4 MBTxtAssetContentMaxSizePDF 最大解析 1024 頁PDFAssetContentMaxPage超過部分不會被索引這對理解「為什麼某些大文件搜不到內容」很關鍵。本版本的兩處修復改進資源文件內容搜索預覽轉義資源內容在檢索命中後會以預覽片段形式回顯到搜索面板若原文包含 HTML 特殊字符如、、而未做轉義預覽會出現渲染錯亂甚至被誤解析為標籤。該版本強化了預覽環節的轉義處理確保命中片段按純文本安全展示。修復內核只讀模式下無法進入主界面內核在readonly模式下會禁用大量寫入型 API可在 kernel/api/router.go 中看到所有model.CheckReadonly中間件掛載點此前該模式下界面初始化流程會因某個被攔截的請求而中斷導致無法進入主界面本次調整了主界面初始化對只讀模式的兼容。EPUB 解析臨時副本 統一文本歸一化「改進 EPUB 資源文件解析」是本次的重頭戲之一。結合 asset_content.go 的EpubAssetParser.Parse實現可以看到 EPUB 內容索引的完整執行鏈路校驗後綴.epub忽略大小寫與文件存在性通過copyTempAsset複製一份臨時文件避免直接解析工作空間內的原文件造成句柄衝突或寫入干擾解析結束後defer os.RemoveAll(tmp)清理調用開源庫github.com/88250/epub的epub.ToTxt將 EPUB 容器內的章節文本抽取為純文本對抽取結果執行normalizeNonTxtAssetContent統一做空白/控制字符歸一化後寫入AssetParseResult.Content供後續 SQL 隊列落庫與檢索使用。本版本優化的重點即在第 3、4 步處理了部分 EPUB 章節文本抽取不完整、格式控制字符殘留等問題使電子書正文能被更完整地納入索引。從代碼結構看PDF 與 EPUB 都走了「複製臨時文件 → 抽取 → 歸一化」的同一套防護模式因此兩者在修復上的收益是共用的。文檔與編輯交互改進本版本在編輯器、浮窗與文檔加載層面有一批細微但影響日常手感的調整逐項梳理如下光標與選擇行為改進劃選文本後 CtrlM 轉換行級公式的光標位置此前在選中文本上直接執行行級公式轉換後光標會落在公式外側需要再次點擊進入本版修正為轉換後光標直接定位於公式內部便於立即繼續輸入。修復文檔聚焦時光標丟失窗口/文檔重新獲得焦點後編輯光標可能不可見本版在聚焦流程中重新校對了光標渲染狀態。修復 ←/→ 鍵無法在引用與超鏈接等文本框中移動光標此類「行內虛擬文本框」此前攔截了方向鍵事件導致用戶無法逐字符移動插入點本次修正了鍵盤事件在 protyle 行內元素上的分發邏輯。光標位於空的代碼塊中時依然可以打開塊標菜單此前空代碼塊在無文本狀態下點擊塊標無響應本版放開了這一限制讓用戶可以對空代碼塊執行插入/刪除等操作。改進選擇文本後的「複製文本 *」右鍵菜單中的「複製文本純文本 / Markdown 等」系列命令在複製結果上做了優化避免把非預期內容如塊屬性、數據標記帶入剪貼板。浮層、浮窗與文檔載入動態計算浮層按 issue #7602 下 wysiwyg 與浮層組件對文檔幾何信息的讀取屬於排版引擎層的改動。浮窗預覽文檔塊時不再自動定位到上一次的瀏覽位置此前打開塊引用浮窗會沿用該文檔此前的滾動位置新版本改為每次以目標塊所在位置為錨點呈現避免「打開浮窗卻看不到引用塊」的困惑。改進 Windows/Linux/macOS amd64 平台上的文檔加載性能針對三大桌面平台 amd64 構建的文檔打開/渲染路徑做了性能調優涉及大文檔的解析與 DOM 構建開銷。改進搜索路徑提示當檢索未命中或命中有限時界面會更明確地提示搜索範圍當前文檔 / 當前子文檔 / 指定路徑 / 全文庫降低「搜不到是範圍問題」的誤解。停靠欄與菜單外觀改進鼠標從外部移入或窗口非激活時停靠欄的顯示/隱藏狀態停靠欄dock bar的顯隱由鼠標懸停與窗口激活狀態共同驅動此前窗口失焦與移入兩個條件疊加時可能出現停靠欄「想藏藏不住、想顯顯不出」的抖動本版在 app/src/layout 的狀態機上統一了判定。改進禁用的菜單按鈕項樣式禁用態菜單項如不滿足前置條件時的「轉換」類操作的視覺區分度得到提升避免與可點擊項混淆。網絡、安全與平台集成改進「網絡圖片轉換為本地圖片」時忽略 HTTPS 證書校驗當用戶導入的圖片資源掛在自簽名證書或校驗鏈異常的 HTTPS 地址上時「下載並轉為本地資源」的流程會因證書錯誤直接失敗。本版在該轉換請求中放開證書校驗讓圖片能被正常抓取落盤此選項僅作用於資源下載環節不影響其他請求的安全策略。改進 Bilibili IFrame 地址解析對 B 站分享地址到嵌入播放器 iframe 的 URL 解析做了容錯支持更多形如b23.tv短鏈或帶額外查詢參數的地址變體。改進 iCloud 路徑檢測在 macOS 上使用 iCloud 驅動器存放工作空間時系統文件路徑可能包含~/Library/Mobile Documents/…的隱式映射本版優化了路徑判別邏輯避免將 iCloud 文件誤判為「工作空間之外」而拒絕讀寫。Windows/macOS 添加「設置 – 關於 – 訪問授權碼 – 跟隨系統鎖屏」桌面端新增跟隨系統鎖屏的授權碼失效策略即檢測到系統鎖屏後要求重新輸入/驗證訪問授權碼。對應設置接口在內核路由中以setFollowSystemLockScreen註冊見 kernel/api/router.go並同樣受CheckAuth/CheckReadonly保護說明它是一項可被內核安全管理體系納管的持久化配置。優化 Windows/macOS 上複製 PDF 標註桌面端從 PDF 註釋高亮/批註複製文本時所見與所得不一致的問題得到修復。移動端改進移動端iOS/Android在本版收穫四項具體修復與優化移動端雲端數據同步圖標不再消失同步狀態圖標此前在特定時序下會從頂欄消失導致用戶無法判斷同步是否在進行本版修正了圖標的顯隱時機。修復移動端代碼塊複製按鈕失效代碼塊右上角複製按鈕在移動端無法觸發剪貼板寫入本版修正了點擊事件與剪貼板 API 的調用鏈。禁止在 iPhone 左側面板頂欄中選擇內容iOS 上長按頂欄會觸發系統級文本選擇干擾面板拖拽與切換本版為頂欄區域禁用了文本選擇。改進 iPhone 輸入元素邊框調整 iOS 輸入框搜索框等的邊框繪製使其在深色模式與不同縮放下保持一致。缺陷修復導入、集市與導出鏈路除前文已涉及的修復外本版還處理了導入、集市與導出三條鏈路上的問題修復導入 .sy.zip 時塊超鏈接未指向重新生成的塊 ID導入打包文檔時內容中指向文檔內其他塊的鏈接若引用舊 ID會因 ID 在導入時被重新生成而失效。本版在導入流程中增加了「舊 ID → 新 ID」的重映射確保塊超鏈接在導入後依然可跳轉。修復集市包更新按鈕不顯示當某個集市包主題/插件/模板/圖標存在新版本時集市面板中的「更新」按鈕在部分版本比較場景下不會渲染本版修復了本地版本與遠端版本的大小比較邏輯。修復導出 PDF 時將資源文件轉換為附件失效PDF 導出配置中「將資源文件轉換為附件」開關在此前未在導出渲染階段生效導致生成的 PDF 依然內嵌圖片而非附帶附件清單本版修正了導出模板對該配置的讀取。開發者插件 API 與內核接口的補全v2.10.3 面向開發者的四項變更是插件生態與第三方集成的重要基礎設施更新插件 APIopenWindow與command.globalCallback按 issue #9032插件 API 新增openWindow方法允許插件以編程方式彈出獨立窗口同時引入command.globalCallback用於向全局命令註冊回調使插件可以攔截/響應既有命令。在 app/src/plugin/API.ts 中可以看到openWindow的簽名設計position?: IPosition窗口位置height/width窗口尺寸tab?: Tab以現有標籤頁作為窗口內容alwaysOnTop?: boolean是否置頂doc?: { id: string }直接以某個文檔塊 ID 打開獨立窗口。實現上openWindow分別路由到openNewWindowById按文檔塊開窗與openNewWindow按 Tab 開窗並透傳位置與置頂參數移動端分支#if MOBILE目前以 TODO 佔位說明該 API 主要面向桌面端。鑑權支持查詢字符串參數token此前調用內核 HTTP API 時訪問令牌通常只能通過請求頭傳遞。按 PR #9069內核鑑權中間件CheckAuth現在同時支持查詢字符串中的token參數例如GET /api/...?...tokenyour_access_token這對受限網絡環境、瀏覽器直接訪問以及無法自定義請求頭的第三方工具更友好。結合內核對/api/...路由的統一CheckAuth掛載方式參見 kernel/api/router.go所有需要鑑權的接口都自動受益。內核 API 行為規範化改進/api/file/getFile響應狀態碼此前該接口在文件不存在或路徑非法時統一返回 200 錯誤體客戶端難以區分成功與失敗本版按 PR #9075。改進/api/network/forwardProxy按 PR #9110在請求轉發與錯誤響應上做了優化提升作為前端服務/插件網絡橋接時的穩定性。小結與升級建議綜合來看v2.10.3 的價值可以概括為三點資源內容搜索走向可用修復了預覽轉義、只讀模式初始化等阻塞性問題並同步優化了 PDF/EPUB 的解析質量讓付費會員的「全文檢索資源文件內容」能力更值得依賴桌面/移動端體驗縫合從光標、浮層、停靠欄到移動端按鈕多項「小毛病」被逐個消除開發者接口補齊openWindow、command.globalCallback、查詢參數token與兩處 HTTP API 行為規範化為插件和外部集成提供了更明確的契約。若你在使用中遇到「資源文件搜不到內容」「EPUB/PDF 導入後內容不完整」或「插件開窗能力缺失」等問題可優先對照本版本的變更清單與上述內核解析鏈路kernel/model/asset_content.go進行驗證若仍無法復現預期行為建議升級至後續版本並結合 CHANGELOG.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），仅供参考