前言¶
在 DSH 里让智能体操作 NAS，常见做法是自建 REST 封装或手写脚本。TrueNAS 自 25.04 起弃用 REST，27 版本起移除；当前应走版本化的 JSON-RPC 2.0 WebSocket API（/api/current）。本文介绍社区插件 dsh-truenas（维护者 Taoidle，分类：联网工具）：把一台或多台 TrueNAS 的配置与 API 密钥纳入 DSH 工具链，供智能体与设置页共用，不依赖额外运行时服务。
这是什么¶
TrueNAS manager for DSH（包名 dsh-truenas，当前资料记载版本 0.10.0，MIT 许可证）是 DeepSeek Harness 插件。它通过 WebSocket 直连 NAS：在新版本上用 auth.login_ex 与 API_KEY_PLAIN 机制，旧版本回退到 auth.login_with_api_key。README 写明除 @deepseek-ai/schemastery 外无额外运行时依赖。
核心功能¶
多实例与凭证¶
- 设置页 Settings → TrueNAS（也可从侧栏 Plugins → TrueNAS manager → Included parts → Configure 进入）为每个 NAS 提供地址、用户、API 密钥与 TLS 选项。
- 密钥在写入 DSH 凭证库前会先向 NAS 校验，避免 typo 留下半配置实例。
- 配置页与工具
truenas_instances管理同一列表；未指定instance时默认使用列表第一项，Make default 可将某台移到首位。 - API 密钥不写入 JSON 配置，而是按实例名派生凭证名（例如
lab-nas→TRUENAS_APIKEY_LAB_NAS）。
全局配置结构示例（资料原文）：
{
"instances": [
{ "name": "lab-nas", "url": "https://nas.lab.local", "username": "root", "insecureTls": true },
{ "name": "backup-nas", "url": "https://10.0.0.9", "username": "admin" }
],
"timeoutMs": 60000,
"jobTimeoutMs": 600000
}
传输与安全¶
插件拒绝 http:// / ws:// 地址再发送密钥：TrueNAS 在非加密连接上展示 API 密钥会立即吊销。insecureTls（页面上的 Skip TLS certificate verification）仅对该实例关闭证书校验，连接仍须 TLS；自签场景更推荐信任 NAS 证书或使用 CA 签发证书。
侧栏概览面板¶
安装 Better Sidebar 后，本 bundle 在右侧栏增加 TrueNAS overview 标签：多实例时用下拉切换。面板通过同源路由 GET /dsh-truenas/panel、GET /dsh-truenas/panel/stream（SSE）、POST /dsh-truenas/panel/action 与 NAS 通信，浏览器不直连 NAS；标签不可见时不刷新。流每 2.5 秒推送快照，无 EventSource 或断流时回退为每 6 秒轮询。
面板覆盖 CPU/内存/池健康、快照一键创建、服务启停与开机项、应用与磁盘自检、证书倒计时、复制与云同步状态、告警消除、作业进度与中止等；部分区块按各自节奏缓存以降低负载。
智能体工具集¶
README 列出面向智能体的工具（节选）：
| 工具 | 用途 |
|---|---|
truenas_instances |
列出 / 增删改 / 测试已配置实例 |
truenas_system |
版本与硬件、告警、服务、引导环境、更新、SSH、可调项等 |
truenas_storage |
池、数据集、创建删除数据集、scrub |
truenas_snapshots |
快照列出、创建、删除、回滚、克隆 |
truenas_shares |
SMB/NFS 共享管理 |
truenas_apps |
TrueNAS Apps / Docker 相关操作 |
truenas_jobs |
作业查询、等待、中止 |
truenas_network |
接口、路由、主机名与 DNS 等 |
truenas_users |
用户组、ACL、权限、API 密钥 |
truenas_replication |
复制任务 |
truenas_cloud |
云同步与云备份任务 |
truenas_alerts |
当前告警（含 dismiss） |
资料在表格处截断，完整列表以仓库 README 为准。
安装与启用¶
在具备 Node 与 npm 的环境中，按 README 准备插件目录：
git clone https://github.com/Taoidle/dsh-truenas.git
cd dsh-truenas
npm install
在 DSH 会话中安装 bundle（路径须为绝对路径）：
plugin_manager action=install_bundle target=/absolute/path/to/dsh-truenas
重新加载 DSH Web UI 后，侧栏 Plugins 中出现 TrueNAS manager。
典型用法¶
用工具添加实例¶
与设置页等价的一种写法：
truenas_instances action="add" name="lab-nas" url="https://nas.lab.local" apiKey="1-xxxxxxxx" insecureTls=true
配置多 NAS¶
可同时管理多台；删除实例需二次确认并会删除对应存储的密钥。
适用场景与注意¶
适合谁：已在用 DSH 编排智能体、且需要对话或自动化里操作 ZFS 池、快照、共享、Apps、复制与云任务等的运维或 homelab 用户。
权限与审阅：插件以当前 DSH 进程权限运行，工具调用等同你对 NAS 的管理能力。安装前请阅读 GitHub 仓库 源码与 MIT 许可证，确认实例 URL 与 API 密钥来源可信。
生态说明：DSH 奉行「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-truenas 把 TrueNAS 的 WebSocket JSON-RPC 封成 DSH 工具与设置页，顺应 REST 退场后的官方 API 方向，并可选配合 Better Sidebar 做只读/轻量操控面板。进一步了解可从目录页与 GitHub 进入：
