開發(fā)工具【免費(fèi)下載鏈接】language-server-protocolDefines a common protocol for language servers.項目地址https://gitcode.com/gh_mirrors/la/language-server-protocol點(diǎn)擊查看免費(fèi)下載導(dǎo)讀window/workDoneProgress/create是 Language Server ProtocolLSP中由**服務(wù)器主動向客戶端發(fā)起工作進(jìn)度Work Done Progress**的核心請求解決了服務(wù)器在請求上下文之外執(zhí)行耗時任務(wù)如重新索引數(shù)據(jù)庫、批量編譯、依賴解析時無法向用戶呈現(xiàn)進(jìn)度的問題。本文基于本倉庫_specifications/lsp/3.17目錄下的規(guī)范文檔結(jié)合 協(xié)議元模型 中對該請求的機(jī)器可讀定義完整講解該請求的協(xié)議形態(tài)、token 生命周期、與$/progress通知的配合方式、取消機(jī)制及客戶端能力協(xié)商幫助你正確實(shí)現(xiàn)服務(wù)器端的進(jìn)度上報。一、背景兩種工作進(jìn)度發(fā)起方式在 LSP 3.15 及之后版本中進(jìn)度上報通過通用的$/progress通知完成其值負(fù)載value payload有三種形態(tài)WorkDoneProgressBegin、WorkDoneProgressReport和WorkDoneProgressEnd對應(yīng)進(jìn)度的開始—更新—結(jié)束三個階段詳見 類型定義。按發(fā)起方不同Work Done Progress 分為兩類發(fā)起方式觸發(fā)途徑典型場景客戶端發(fā)起client initiated客戶端在請求參數(shù)中加入workDoneToken屬性客戶端發(fā)起的textDocument/reference等請求上附帶進(jìn)度 token服務(wù)器發(fā)起server initiated服務(wù)器發(fā)送window/workDoneProgress/create請求服務(wù)器需要在某個請求之外自行上報進(jìn)度如后臺重新索引數(shù)據(jù)庫本篇文章聚焦第二種方式——服務(wù)器發(fā)起的進(jìn)度。二、協(xié)議定義方法、參數(shù)與響應(yīng)請求方向與方法名window/workDoneProgress/create是一個從服務(wù)器發(fā)往客戶端server-to-client的請求用于請求客戶端創(chuàng)建一個工作進(jìn)度實(shí)例。這一方向性在協(xié)議元模型中有明確記錄在 metaModel.json 中該請求的messageDirection字段為serverToClientresult類型為null文檔注釋為Thewindow/workDoneProgress/createrequest is sent from the server to the client to initiate progress reporting from the server.請求參數(shù)WorkDoneProgressCreateParams請求參數(shù)類型定義如下export interface WorkDoneProgressCreateParams { /** * The token to be used to report progress. */ token: ProgressToken; }其中ProgressToken是integer | string的聯(lián)合類型見 specification.md 與 metaModel.json。服務(wù)器在發(fā)起 create 請求時需自行生成一個唯一 token實(shí)踐中常用 UUID 字符串該 token 將作為后續(xù)所有$/progress通知中標(biāo)識此進(jìn)度實(shí)例的鍵。響應(yīng)與錯誤處理成功響應(yīng)result為void即無返回值客戶端確認(rèn)已創(chuàng)建進(jìn)度。錯誤響應(yīng)若請求處理過程中發(fā)生異?？蛻舳朔祷豦rror.code與error.message。規(guī)范對錯誤情形有一個關(guān)鍵約束如果 create 請求出錯服務(wù)器絕不能使用該 token 發(fā)送任何進(jìn)度通知。這保證了錯誤發(fā)生后客戶端不會收到與已失敗進(jìn)度關(guān)聯(lián)的幽靈更新是保證進(jìn)度 UI 一致性的底線規(guī)則。三、服務(wù)器發(fā)起進(jìn)度的完整生命周期根據(jù) types/workDoneProgress.md 中的Server Initiated Progress一節(jié)服務(wù)器發(fā)起的進(jìn)度遵循以下完整流程1. 創(chuàng)建進(jìn)度create服務(wù)器在需要上報進(jìn)度時例如準(zhǔn)備開始重索引先向客戶端發(fā)送{ jsonrpc: 2.0, id: 10, method: window/workDoneProgress/create, params: { token: 2f8a4c12-9d3b-4e76-9c1a-7b0f3a56e2d1 } }2. 發(fā)送 begin 通知創(chuàng)建成功后服務(wù)器通過$/progress通知發(fā)送WorkDoneProgressBegin負(fù)載title為必填項用于簡短說明正在執(zhí)行的操作類型{ jsonrpc: 2.0, method: $/progress, params: { token: 2f8a4c12-9d3b-4e76-9c1a-7b0f3a56e2d1, value: { kind: begin, title: Indexing workspace, cancellable: true, message: Scanning project/src, percentage: 0 } } }WorkDoneProgressBegin的字段語義類型定義字段類型必填說明kindbegin是負(fù)載形態(tài)標(biāo)記titlestring是進(jìn)度的標(biāo)題如Indexing或Linking dependenciescancellableboolean否是否顯示取消按鈕不支持取消的客戶端可忽略messagestring否更詳細(xì)的進(jìn)度消息如3/25 files未設(shè)置時沿用上一次消息percentageuinteger否進(jìn)度百分比100視為 100%不提供則視為無限進(jìn)度取值范圍[0, 100]應(yīng)保持單調(diào)遞增3. 周期性發(fā)送 report 通知任務(wù)執(zhí)行過程中服務(wù)器發(fā)送WorkDoneProgressReport更新進(jìn)度{ jsonrpc: 2.0, method: $/progress, params: { token: 2f8a4c12-9d3b-4e76-9c1a-7b0f3a56e2d1, value: { kind: report, message: 12/50 files, percentage: 24 } } }WorkDoneProgressReport支持cancellable、message、percentage三個可選字段其中cancellable僅在 begin 中請求了取消按鈕時有效。4. 發(fā)送 end 通知收尾任務(wù)完成或失敗時發(fā)送WorkDoneProgressEnd{ jsonrpc: 2.0, method: $/progress, params: { token: 2f8a4c12-9d3b-4e76-9c1a-7b0f3a56e2d1, value: { kind: end, message: Indexing finished } } }WorkDoneProgressEnd僅含可選的message字段可用于說明操作結(jié)果。token 的使用約束規(guī)范明確要求create 請求中提供的 token 只能使用一次——即對該 token 應(yīng)恰好發(fā)送一個begin、任意多個report和一個end通知。這與客戶端發(fā)起的進(jìn)度形成對比客戶端通過請求參數(shù)中的workDoneToken傳入的 token其有效期只持續(xù)到該請求返回響應(yīng)為止。四、取消機(jī)制window/workDoneProgress/cancel服務(wù)器發(fā)起的進(jìn)度同樣支持取消?？蛻舳送ㄟ^window/workDoneProgress/cancel通知client-to-server 方向取消進(jìn)度參數(shù)類型為export interface WorkDoneProgressCancelParams { /** * The token to be used to report progress. */ token: ProgressToken; }協(xié)議要點(diǎn)見 workDoneProgressCancel.md取消的進(jìn)度無需在 begin 中標(biāo)記為cancellable——也就是說即使服務(wù)器未提供取消按鈕客戶端仍然可以主動取消進(jìn)度客戶端可能因多種原因取消進(jìn)度發(fā)生錯誤、重載工作區(qū)等服務(wù)器收到該通知后應(yīng)終止對應(yīng)任務(wù)并發(fā)送end通知收尾或依據(jù)自身實(shí)現(xiàn)決定處理方式。此外對于客戶端發(fā)起的進(jìn)度取消則直接通過取消對應(yīng)請求如$/cancelRequest完成無需單獨(dú)的 cancel 通知。五、客戶端能力協(xié)商與向后兼容為保持協(xié)議向后兼容服務(wù)器只有在客戶端通過能力聲明明確支持時才能使用window/workDoneProgress/create請求?？蛻舳嗽?initialize 握手階段返回的ClientCapabilities中聲明window?: { /** * Whether client supports server initiated progress using the * window/workDoneProgress/create request. */ workDoneProgress?: boolean; };對應(yīng)客戶端能力屬性為window.workDoneProgress類型為boolean可選。服務(wù)器在發(fā)起 create 請求前必須檢查該能力位若客戶端未聲明支持服務(wù)器應(yīng)退回到客戶端發(fā)起的方式或在請求參數(shù)中附帶的workDoneToken上上報進(jìn)度甚至放棄進(jìn)度展示。與之相對客戶端發(fā)起方式有一個特別之處不存在專門的客戶端能力位來聲明是否會在每個請求上發(fā)送進(jìn)度 token。因為這在很多客戶端中并非靜態(tài)屬性甚至同一請求類型的不同請求實(shí)例都可能不同所以客戶端能力通過每個請求參數(shù)中是否出現(xiàn)workDoneToken屬性來按實(shí)例動態(tài)表達(dá)見 types/workDoneProgress.md 中 Client Initiated Progress 一節(jié)。同時為避免客戶端在發(fā)送請求前建立進(jìn)度 UI 而服務(wù)器實(shí)際不報進(jìn)度服務(wù)器需要在對應(yīng)功能的 server capability 中聲明workDoneProgress支持例如{ referencesProvider: { workDoneProgress: true } }六、從元模型看協(xié)議定義的一致性本倉庫在 metaModel 目錄 中提供了 LSP 3.17 的機(jī)器可讀元模型metaModel.json、metaModel.schema.json與對應(yīng)的 TypeScript 模型metaModel.ts可用于校驗與代碼生成。其中與本文主題相關(guān)的定義包括window/workDoneProgress/create 請求定義messageDirection: serverToClient、result: null、params: WorkDoneProgressCreateParamsWorkDoneProgressCreateParams 結(jié)構(gòu)僅含token: ProgressToken一個屬性WorkDoneProgressCancelParams 結(jié)構(gòu)同樣僅含token: ProgressTokenProgressToken 類型integer | string。元模型中的這些定義與各 Markdown 規(guī)范文檔完全一致說明該請求在協(xié)議中作為一等公民被完整建模。如果你在實(shí)現(xiàn)語言服務(wù)器 SDK 時使用元模型驅(qū)動代碼生成window/workDoneProgress/create會自然生成對應(yīng)的請求類型、參數(shù)類型與文檔注釋。七、實(shí)現(xiàn)建議小結(jié)能力先行發(fā)送 create 請求前務(wù)必檢查客戶端能力window.workDoneProgress是否為true。token 唯一且單次使用每個進(jìn)度實(shí)例使用獨(dú)立的ProgressToken遵守一個 begin、多個 report、一個 end的規(guī)則。正確處理 create 失敗create 請求報錯后該 token 立即作廢不得再發(fā)送任何$/progress通知。響應(yīng)取消監(jiān)聽window/workDoneProgress/cancel通知收到后盡快終止任務(wù)并發(fā)送end負(fù)載。善用元模型以 metaModel.json 為單一事實(shí)來源生成類型定義避免手寫結(jié)構(gòu)與規(guī)范漂移。通過以上機(jī)制語言服務(wù)器可以在索引、編譯、依賴分析等請求外的長耗時操作中向用戶提供可取消、可感知的進(jìn)度反饋顯著改善編輯器的交互體驗——這正是 LSP 3.15 引入工作進(jìn)度機(jī)制、并讓服務(wù)器側(cè)發(fā)起進(jìn)度的設(shè)計初衷。贊分享開發(fā)工具【免費(fèi)下載鏈接】language-server-protocolDefines a common protocol for language servers.項目地址https://gitcode.com/gh_mirrors/la/language-server-protocol點(diǎn)擊查看免費(fèi)下載相關(guān)推薦KOReader 上手教程免費(fèi)在 Kindle 和 Kobo 上讀 20 多種電子書格式KOReader 上手教程免費(fèi)在 Kindle 和 Kobo 上讀 20 多種電子書格式 KOReader 是一款免費(fèi)開源的電子書閱讀器主要解決設(shè)備自帶閱讀開發(fā)工具TeleChat2.5-35B的vLLM服務(wù)化部署實(shí)戰(zhàn)教程10個步驟快速搭建AI推理服務(wù)TeleChat2.5 35B的vLLM服務(wù)化部署實(shí)戰(zhàn)教程10個步驟快速搭建AI推理服務(wù) TeleChat2.5 35B是中國電信人工智能研究院研發(fā)的35B參如何快速搭建高效Node.js服務(wù)器example-node-server完整指南如何快速搭建高效Node.js服務(wù)器example node server完整指南 example node server 是一個基于Babel的輕量級Nod上一篇Klipper實(shí)戰(zhàn)如何讓3D打印機(jī)實(shí)現(xiàn)智能參數(shù)自適應(yīng)調(diào)校下一篇Tkinter表格組件終極指南用tksheet構(gòu)建專業(yè)級數(shù)據(jù)界面創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考