工作區信任擴充功能指南
什麼是工作區信任 (Workspace Trust)？
工作區信任是一項功能，旨在解決使用者在 VS Code 中開啟工作區時，因非預期的程式碼執行所帶來的安全性風險。例如，考慮到某個語言擴充功能為了提供功能，可能會執行來自目前已載入工作區的程式碼。在這種情況下，使用者應該信任工作區的內容並非惡意。工作區信任將此決策集中在 VS Code 內，並支援限制模式 (Restricted Mode) 以防範自動執行程式碼，因此擴充功能開發者無需自行處理此基礎架構。VS Code 提供靜態宣告和 API 支援，以便快速導入擴充功能，而無需在各個擴充功能中重複撰寫程式碼。
導入 (Onboarding)
靜態宣告
在擴充功能的 package.json 中，VS Code 支援下列新的 capabilities 屬性：untrustedWorkspaces
capabilities:
untrustedWorkspaces:
{ supported: true } |
{ supported: false, description: string } |
{ supported: 'limited', description: string, restrictedConfigurations?: string[] }
針對 supported 屬性，可接受下列值：
true- 該擴充功能在「限制模式」下完全支援，因為它不需要工作區信任即可執行任何功能。它將會與之前一樣正常啟用。false- 該擴充功能在「限制模式」下不支援，因為沒有工作區信任便無法運作。在授予工作區信任之前，它將保持停用狀態。'limited'- 擴充功能的部分功能在「限制模式」下受到支援。對信任敏感的功能應在授予工作區信任前保持停用。擴充功能可以使用 VS Code API 來隱藏或停用這些功能。工作區設定可以透過restrictedConfigurations屬性自動根據信任狀態進行限制。
對於 description 屬性，必須提供為何需要信任的說明，以協助使用者了解哪些功能將被停用，或在授予或拒絕工作區信任之前應審查的內容。若 supported 設定為 true，則此屬性將被忽略。
description 屬性的值應新增至 package.nls.json，然後在 package.json 檔案中參照，以提供在地化支援。
restrictedConfigurations 屬性接受一組設定 ID 陣列。對於列出的設定，當處於非信任工作區的「限制模式」時，擴充功能將不會獲得工作區定義的值。
如何支援「限制模式」？
為了協助擴充功能開發者了解工作區信任的範疇，以及在「限制模式」下哪些類型的功能是安全的，請參考以下問題清單：
我的擴充功能是否有主要進入點 (Main Entry Point)？
如果擴充功能沒有 main 進入點（例如主題和語言文法），則該擴充功能不需要工作區信任。擴充功能開發者無需針對此類擴充功能採取任何行動，因為無論工作區是否受信任，它們都將繼續運作。
我的擴充功能是否依賴於已開啟工作區中的檔案來提供功能？
這可能意味著工作區設定的設定值，或是工作區中的實際程式碼。如果擴充功能從未使用工作區的任何內容，則可能不需要信任。否則，請查看其他問題。
我的擴充功能是否將工作區的任何內容視為程式碼處理？
最常見的例子是使用專案的工作區相依項，例如儲存在本機工作區中的 Node.js 模組。惡意工作區可能會引入被竄改的模組版本。因此，這對使用者和擴充功能來說都是安全風險。此外，擴充功能可能依賴於控制擴充功能或模組行為的 JavaScript 或其他設定檔。還有許多其他範例，例如為了錯誤報告而執行已開啟的程式碼檔案以確定其輸出。
我的擴充功能是否使用可在工作區中定義、並決定程式碼執行的設定？
您的擴充功能可能會使用設定值作為 CLI 的旗標，並由擴充功能執行該 CLI。如果這些設定被惡意工作區覆寫，它們可能會被用作針對您擴充功能的攻擊向量。另一方面，如果設定值僅用於偵測特定條件，則可能沒有安全風險，也就不需要工作區信任。例如，擴充功能可能會檢查慣用 Shell 設定的值是 bash 還是 pwsh，以決定要顯示什麼文件。下方的設定 (Configurations) 章節提供了關於設定的指導，以協助您為擴充功能找到最佳配置。
這並非可能需要工作區信任的所有情況清單。隨著我們審查更多的擴充功能，我們將會更新此清單。在考慮工作區信任時，請使用此清單來思考您的擴充功能可能進行的類似行為。
如果我不對我的擴充功能進行任何變更會怎樣？
如上所述，若擴充功能未在 package.json 中貢獻任何內容，將會被視為不支援工作區信任。當工作區處於「限制模式」時，它將會被停用，且使用者會收到通知，告知某些擴充功能因工作區信任問題而無法運作。此舉是對使用者最安全的做法。儘管這是預設行為，但作為擴充功能開發者，設定適當的值以表明您已努力保護使用者和您的擴充功能免受惡意工作區內容的侵害，這是一項最佳實務。
工作區信任 API
如上所述，使用 API 的第一步是在 package.json 中新增靜態宣告。最簡單的導入方法是將 supported 屬性設為 false。再次強調，即使您什麼都不做，這也是預設行為，但這對使用者來說是一個很好的訊號，表示您已做出審慎的選擇。在這種情況下，您的擴充功能無需執行任何其他操作。除非獲得信任，否則它不會被啟用；一旦啟用，您的擴充功能就會知道它是在獲得使用者同意的情況下執行。然而，如果您的擴充功能僅在部分功能需要信任，這可能不是最好的選擇。
對於希望根據工作區信任來控制功能的擴充功能，應將 supported 屬性設為 'limited'，而 VS Code 提供了以下 API：
export namespace workspace {
/**
* When true, the user has explicitly trusted the contents of the workspace.
*/
export const isTrusted: boolean;
/**
* Event that fires when the current workspace has been trusted.
*/
export const onDidGrantWorkspaceTrust: Event<void>;
}
使用 isTrusted 屬性來判斷目前的工作區是否受信任，並使用 onDidGrantWorkspaceTrust 事件來監聽工作區何時獲得信任。您可以使用此 API 來阻擋特定的程式碼路徑，並在工作區受信任後執行任何必要的註冊。
VS Code 還公開了一個內容鍵 (context key) isWorkspaceTrusted，供 when 子句使用，詳情如下。
貢獻點 (Contribution points)
命令、檢視或其他 UI
當使用者未信任工作區時，他們將會在「限制模式」下操作，功能僅限於瀏覽程式碼。您在「限制模式」下停用的任何功能都應對使用者隱藏。這可以透過 when 子句內容和內容鍵 isWorkspaceTrusted 來完成。即使命令未顯示在 UI 中，仍然可以被呼叫，因此您應該根據上述的 API 在擴充功能程式碼中阻擋執行或不註冊該命令。
配置 (設定)
首先，您應該審查您的設定，以確定是否需要考量信任問題。如上所述，工作區可能會為您的擴充功能所使用的設定定義惡意值。如果您識別出有漏洞的設定，您應該將 supported 屬性設為 'limited'，並將該設定 ID 列在 restrictedConfigurations 陣列中。
當您將設定 ID 新增至 restrictedConfigurations 陣列時，VS Code 在「限制模式」下將僅回傳該設定的使用者定義值。這樣您的擴充功能就不需要進行任何額外的程式碼變更來處理該設定。當獲得信任時，除了工作區信任事件外，還會觸發配置變更事件。
偵錯擴充功能
VS Code 將在「限制模式」下禁止偵錯。因此，偵錯擴充功能通常不需要要求信任，且應為 supported 屬性選擇 true。然而，如果您的擴充功能提供了內建偵錯流程以外的額外功能、命令或設定，則應使用 'limited' 並遵循上述指導。
工作提供者 (Task providers)
與偵錯類似，VS Code 在「限制模式」下會防止執行工作 (Tasks)。如果您的擴充功能提供了內建工作流程以外的額外功能、命令或設定，則應使用 'limited' 並遵循上述指導。否則，您可以指定 supported: true。
測試工作區信任
請參閱工作區信任使用者指南以取得啟用和設定工作區信任的詳細資訊。