前言¶

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 工作流中，适合需要频繁访问凭据的智能体场景。