前言¶

DeepSeek Harness (DSH) 的核心理念是“一切皆插件”。在開發或使用智能體時，經常會遇到需要訪問密碼庫、API 密鑰或 TOTP 驗證碼的場景。傳統的做法是手動複製粘貼，效率低且存在安全風險。

buvkb/dsh-vaultwarden 是一個連接 Vaultwarden 或 Bitwarden 服務器的插件。它不依賴本地的 bw CLI，而是直接通過 REST API 和 SignalR 協議與服務器通信，爲 DSH 提供實時同步、讀寫工具以及可視化的條目瀏覽面板。

核心能力¶

該插件提供以下核心功能：

實時同步引擎：支持 WebSocket（SignalR）推送，服務器變更即時反映到本地。若 WebSocket 不可用（如反代未放行或舊服務器），會自動降級爲輪詢（30–120 秒），並在可用時自動升級回 WebSocket。支持限流自動退避。
9 個全局工具：包括檢索、獲取字段、狀態檢查、強制同步、文件夾管理、恢復條目、創建、更新和刪除條目。
系統提示詞注入：可在全局注入引導，提示模型先在憑據庫中查找信息，而不是直接詢問用戶。
條目瀏覽面板：提供層級分區菜單（全部、收藏、驗證碼、類型、文件夾、歸檔、回收站），支持搜索、列表展示、詳情查看和 TOTP 倒計時（SVG 圖標）。
認證通道：面板通過 /api connection RPC 取數，走操作者已認證的會話，插件不自建 HTTP 路由。
配置表單：支持 12 個字段的配置項，涵蓋服務器地址、登錄憑證、同步策略、權限檔和會話管理等。

插件支持通過 DSH 設置界面、環境變量或組合配置進行設置。

1. DSH 設置界面
在設置 → 插件 → 插件配置 → Bitwarden / Vaultwarden 憑據庫中配置。主密碼與 API 密鑰爲只寫字段。

serverUrl：服務器地址，如 https://vault.example.com。
email：登錄郵箱，必須與賬號一致，作爲 KDF 鹽值。
masterPassword：主密碼，用於解密保險庫。
apiKeyClientId / apiKeyClientSecret：可選。使用 API 密鑰登錄，可繞過兩步驗證。
websocket：啓用 WebSocket 實時通知（默認開啓）。
pollIntervalSeconds：WebSocket 不可用時的兜底輪詢間隔（默認 300 秒）。
cacheMinutes：解鎖後的內存緩存時長（默認 30 分鐘）。
localCache：本地密文緩存（默認開啓），用於快速啓動和變更探測。
deviceIdentifier：可選設備標識。留空則按“服務器+郵箱”確定性派生。
accessMode：寫權限控制。readonly（默認，拒絕寫回）、ask（需用戶確認）、auto（直接寫回）。此限制僅對模型工具生效，面板人工操作不受限制。
sessionDays：登錄會話保留天數（默認 30）。
repromptGrantMinutes：重新驗證條目的記憶時間（默認 5 分鐘）。

2. 環境變量
支持以下環境變量（支持 DSH_ 前綴或無前綴）：
SERVER_URL、EMAIL、MASTER_PASSWORD、CLIENT_ID、CLIENT_SECRET、DEVICE_ID。

插件提供多種工具供模型調用。

1. 檢索與獲取
* bitwarden_find：檢索條目。支持按名稱、用戶名、URL、備註等查詢。默認不含密碼、歸檔與回收站條目。

    bitwarden_find { "query": "github" }

    bitwarden_get { "id": "…", "field": "password" }
    bitwarden_get { "id": "…", "field": "totp", "waitFresh": true }

    bitwarden_status { "refresh": true }

2. 同步與維護
* bitwarden_sync：強制同步。

    bitwarden_sync { }

    bitwarden_folders { }

    bitwarden_restore { "id": "…" }

3. 寫入操作
寫入操作需要 accessMode 爲 ask 或 auto。
* bitwarden_create：創建新條目。

    bitwarden_create { "name": "新站點", "username": "…", "password": "…" }

    bitwarden_update { "id": "…", "password": "新密碼" }

    bitwarden_delete { "id": "…" }

TOTP 使用注意：
TOTP 碼有效期僅爲 30 秒。若使用 waitFresh，插件會等待一個至少剩餘 minRemaining 秒（默認 20）的窗口再返回，避免拿到馬上過期的碼。freshFor 字段會返回碼還剩多少秒可用。

Node 版本：要求 Node.js >= 22。
依賴：不依賴 bw CLI，除可選的 hash-wasm（Argon2id KDF）外使用 Node 內置模塊。
權限：插件以當前 DSH 進程的權限運行，安裝前應檢查源碼與許可證。
面板權限：面板操作通過已認證會話的 RPC 執行，不受 accessMode 寫權限限制，但需謹慎操作。
徹底刪除：面板與 RPC 均不提供徹底刪除入口，徹底刪除需通過 bitwarden_delete 工具並設置 permanent: true 和 confirm: true。

dsh-vaultwarden 通過 WebSocket 實時同步和便捷的工具接口，將 Bitwarden/Vaultwarden 集成到了 DSH 工作流中，適合需要頻繁訪問憑據的智能體場景。