前言¶
在 DSH 裏，工作區往往對應真實磁盤路徑，側欄裏會掛着多條會話。多人共用機器、偶爾把瀏覽器留在前臺，或者本機裏還有別的同事能點開同一個 DSH 頁面時，「整條工作區樹在界面上裸露」會變成一種很具體的尷尬：不用進終端，點幾下就能看見某個目錄下的對話歷史。
逐個會話加鎖、或者靠操作系統賬戶隔離，都能緩解一部分問題，但和「按文件夾整棵收起來」不是同一種模型。dsh-workspace-lock（維護者 phzt-hub，社區分類 admin-security）做的是後者：在 Web 界面裏給整個工作區文件夾加密碼鎖，鎖上後側欄收起該文件夾、其下會話行批量隱藏，鎖/解鎖集中在「工作區鎖」面板；忘記密碼可走 QQ 郵箱驗證碼重置。下文按安裝、日常使用、邊界與找回說明，事實以插件 README 與倉庫元數據爲準。
這是什麼¶
dsh-workspace-lock 是跑在 DSH web profile 上的 Cordis 插件，當前倉庫版本爲 0.2.2，許可證 MIT，要求 Node ≥ 20。它不加密磁盤上的項目文件，而是在 DSH 側欄與主界面裏做「門禁」：鎖定後界面上看不見、點不進該文件夾及其會話；本機其他程序、命令行、備份仍能讀到明文——防的是別人隨手點開你的 DSH。
核心功能¶
文件夾級鎖定，不是逐個會話鎖¶
鎖定對象是整個工作區文件夾。一鎖上，側欄裏該文件夾立刻收起，內部會話行整批隱藏，不會出現「每個會話彈一次密碼頁」的逐個會話鎖。鎖/解鎖都在「工作區鎖」面板完成。
三種操作語義¶
面板裏每個文件夾一行，對應三種動作：
- 鎖定：進入鎖定狀態，側欄收起、會話隱藏。
- 解鎖（只在本頁）：僅在當前頁面臨時解開；刷新後重新鎖上。
- 解除鎖定（永久，需要密碼）：從狀態文件裏刪掉該路徑的鎖定記錄，需驗證總密碼。
自動重新上鎖¶
默認 15 分鐘無操作自動重新上鎖；可在面板裏修改，設爲 0 表示不自動鎖。
QQ 郵箱找回密碼¶
忘記總密碼時，可用 QQ 郵箱收 6 位驗證碼重置（10 分鐘有效，最多試 5 次）。鎖定頁與面板都提供找回入口；改找回郵箱需總密碼，防止他人把自己的郵箱寫進配置再走找回流程。
宿主 API 與狀態持久化¶
密碼與鎖定路徑由宿主側 API 管理，狀態默認寫在 $DSH_HOME/workspace-lock/state.json（未設置 DSH_HOME 時爲 ~/.dsh/workspace-lock/state.json，權限 0600）。密碼僅存 scrypt 派生值；SMTP 授權碼寫在同一文件，不回傳頁面。主要路由包括：
GET /api/ws-lock/statePOST /api/ws-lock/password、/verify、/toggle、/configPOST /api/ws-lock/test-email、/recover/request、/recover/verify
界面通過多處插槽掛載：sidebar.panellist 增加鎖圖標面板，main 展示文件夾清單與配置，shell.overlay 在兜底場景用全屏密碼頁擋住進入鎖定目錄的會話；側欄對文件夾行的收起與會話隱藏因 DSH 未提供專用鉤子，插件在 shell.overlay 側結合 DOM 與會話/工作區 props 實現（DSH 升級側欄結構時，最壞情況是「不再收起」或「會話仍顯示」，而非進程崩潰）。
安裝與啓用¶
插件屬 web profile，宿主端僅使用 Node 內置模塊（crypto / fs / os / path / tls），無原生依賴，也不依賴外部託管服務。安裝任選其一：
# 從 npm 安裝
dsh plugin --profile web add dsh-workspace-lock
# 或者直接從 GitHub 源碼安裝
dsh plugin --profile web add github:phzt-hub/dsh-workspace-lock
裝完後必須重啓 dsh web：宿主端代碼需重啓才生效（瀏覽器端模塊可熱替換）。重啓後左側側欄出現鎖圖標，點開即「工作區鎖」面板。
若需改狀態文件位置，可在 cordis.patch.yml 對應條目下增加 config.statePath，例如：
- id: dsh-workspace-lock
config:
statePath: /opt/dsh/workspace-lock/state.json
典型用法¶
首次：設總密碼並鎖定文件夾¶
- 打開側欄鎖圖標，進入「工作區鎖」面板。
- 設置總密碼（後續鎖定、永久解除、改找回郵箱都會用到）。
- 在文件夾清單中對目標路徑點「鎖定」。
鎖定後側欄該文件夾收起，其下會話不可見；若從其他入口誤入鎖定目錄下的會話，shell.overlay 會用全屏密碼頁兜底。
臨時查看：只在本頁解鎖¶
需要短時間查看內容時，使用「解鎖（只在本頁）」。看完刷新頁面即恢復鎖定，無需改狀態文件。
不再需要鎖：永久解除¶
確認不再對該文件夾做界面鎖定時，使用「解除鎖定（永久，需要密碼）」，會從 state.json 的 lockedPaths 中移除該路徑。
配置 QQ 郵箱找回¶
在 QQ 郵箱：設置 → 賬戶 → 開啓 POP3/SMTP 服務 → 生成授權碼（不是登錄密碼）。在面板填入郵箱與授權碼後，先點「發一封測試郵件」確認鏈路，再依賴「忘記密碼」流程收驗證碼設新密碼。
自動鎖 idle 時間¶
在面板調整自動重新上鎖分鐘數；設爲 0 關閉 idle 自動鎖，僅保留手動鎖定與刷新後恢復鎖的行爲（針對「只在本頁解鎖」）。
適用場景與注意¶
適合誰： 同一臺機器或同一瀏覽器會話可能被他人短暫使用、又希望在 DSH 裏按目錄粒度隱藏整塊工作區與會話時，可用本插件做界面層門禁。社區目錄將其歸爲 admin-security，側重管理面的訪問控制，而非存儲加密。
務必區分的邊界： README 明確說明這是門禁，不是磁盤加密。鎖定後 DSH 內不可見、不可進，但本機其他程序與備份仍能讀明文。
插件權限： 插件以當前 dsh web 進程權限運行，狀態文件與 API 在同一宿主進程內處理。安裝前建議自行查看 GitHub 倉庫 源碼與 MIT 許可證，確認符合你的安全策略。
忘記密碼且未配郵箱： 鎖屏與面板都無法進入時，只能停掉 DSH，編輯 ~/.dsh/workspace-lock/state.json，刪除 password 與 lockedPaths（或刪除整個文件）後重啓。「只在本頁解鎖」本身只在瀏覽器內存，刷新也會回到鎖定。
開發與升級： 修改宿主代碼後同樣需要重啓 dsh web；倉庫提供 node test/smoke.mjs 等校驗，界面行爲需在裝進 profile 後在瀏覽器中確認。
結尾¶
dsh-workspace-lock 把「工作區文件夾 + 其下全部會話」收成一把總鎖，操作集中在「工作區鎖」面板，並可選 QQ 郵箱找回與 idle 自動重鎖。若你正在 DSH 生態裏找目錄級界面隱藏而非全盤加密，可以從 npm 或 GitHub 安裝，重啓 dsh web 後從側欄鎖圖標開始配置。
