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