前言¶
在 DSH 里做运维或巡检时，Agent 往往需要读主机状态、拉日志或在受控范围内执行一次性命令。若监控面板与智能体环境彼此隔离，通常要单独写脚本、维护 API 凭据，再把能力手工挂到工具列表上。哪吒监控（Nezha Monitoring）V2 内置 MCP 服务，可通过 POST /mcp 暴露服务器清单、远程执行与文件操作等工具；dsh-nezha 由维护者 kaecho 提供，负责把该端点接到 DeepSeek Harness，并在插件详情页用可视化表单管理地址与 PAT。下面按安装、配置与工具命名说明用法。
插件定位¶
dsh-nezha（GitHub：kaecho/dsh-nezha）是 DSH 客户端类插件：连接 Nezha Dashboard 的 MCP 端点，使用 Authorization: Bearer nzp_... 认证。当前版本为 0.1.0，许可证 MIT。运行要求为 DSH >=0.2.1-rc.2、Node.js >=22（开发与打包；DSH 运行时自带 Node），以及已开启 MCP 的 Nezha V2。
插件无运行时外部依赖，无需额外构建。保存配置后会自动执行 MCP initialize、notifications/initialized 和 tools/list，并将 Nezha 工具动态注册到 DSH，统一命名为 mcp__nezha__<tool>。
环境准备¶
在接入插件之前，需要同时满足 DSH、Nezha 与网络三侧条件。
| 项目 | 要求 |
|---|---|
| DeepSeek Harness | >=0.2.1-rc.2 |
| Nezha | V2，且 enable_mcp: true |
| 认证 | Nezha API Token（PAT），以 nzp_ 开头；不能使用浏览器登录 JWT |
| 网络 | DSH 所在主机能通过 HTTP(S) 访问 Dashboard 的 /mcp |
| 反向代理 | 允许 POST /mcp，转发 Authorization，请求体上限至少 8 MiB |
Nezha 的 MCP 默认关闭。在 Dashboard 配置中开启后需重启或重新加载，使 /mcp 生效：
enable_mcp: true
核心能力¶
- 连接与注册：对接
POST /mcp；启动或保存配置后拉取tools/list并注册到 DSH。 - Web UI 设置：在插件详情页（
plugins.bundle.config）配置 Dashboard 地址、PAT、启用/停用、超时；支持测试连接、保存、刷新工具、清除已保存令牌。 - 错误可读化：连接失败、认证失败、权限不足、404、限流和超时会转换为可读提示。
- 凭据分离：PAT 写入 DSH 凭据记录
dsh-nezha/token；普通设置文件仅含url、enabled、timeoutMs。 - 传输形态：兼容 JSON 与 SSE 形式的 MCP 响应；Nezha 当前为 POST 请求/响应模式，不依赖长连接 SSE。
安装与启用¶
当前版本以 GitHub Release 的 .tgz 和本地目录安装为主，尚未发布到 npm。资料中未给出 dsh plugin add github:... 一类命令，应在 DSH Web UI 的 Plugins / 插件 页面添加。
从本地目录安装（开发/自用推荐）¶
- 将本仓库放到 DSH 所在主机，例如
/path/to/dsh-nezha。 - 在插件页选择添加插件，在「包名或地址」中填写该目录的绝对路径。
- 安装并保持启用；若提示
restart-required，重启 DSH 后再打开插件详情页。
从本地 .tgz 安装¶
在仓库根目录执行：
npm pack
会生成 dsh-nezha-0.1.0.tgz。在 DSH 插件页选择从本地安装，指向该文件即可；插件无外部依赖，安装时不需要执行依赖构建脚本。
从 npm 安装（发布后）¶
发布到 npm 后，可在「包名或地址」中填写 dsh-nezha 按包名安装。
安装完成后，插件列表中应出现标题为 Nezha MCP / 哪吒 MCP 的条目。
首次配置¶
- 打开 Plugins / 插件，进入
dsh-nezha详情页。 - 在配置区填写：
| 字段 | 说明 |
|---|---|
| Dashboard 地址 | 可填 https://nezha.example.com 或含路径/完整 /mcp 的 URL；插件会规范化为 /mcp。勿带用户名、密码、查询参数或片段。 |
| API Token / PAT | 以 nzp_ 开头；留空表示保留已保存令牌。 |
| 启用 | 关闭则不连接、不注册工具。 |
| 超时 | 单次 MCP 请求 5–300 秒，默认 60 秒；长耗时 server.exec 需调大并同步反向代理超时。 |
- 点击 测试连接：对当前表单地址与 PAT（PAT 留空则用已保存值）执行
initialize与tools/list，不保存配置、不执行命令或文件操作。 - 点击 保存并连接：写入 profile 设置与凭据，自动重连并刷新工具。
- Nezha 侧 PAT scope、白名单或版本变更后，使用 刷新工具 重新读取
tools/list。 - 撤销本地 PAT：勾选 清除已保存的 PAT（保存时生效） 后保存。
非机密配置落在当前 profile 目录下 <profile>/dsh-nezha/settings.json（由环境变量 DSH_PROFILE_DIR 指向的 profile 目录决定）。
Agent 侧工具命名与权限¶
DSH 注册名格式为 mcp__nezha__<tool>。Nezha 原始名中的点号会替换为下划线，例如：
| Nezha 原始工具 | DSH 工具名 |
|---|---|
server.list |
mcp__nezha__server_list |
server.exec |
mcp__nezha__server_exec |
fs.read |
mcp__nezha__fs_read |
在 Nezha Dashboard 的 API / API Token（PAT） 页面创建 Token，按需选择 scope 与服务器 ID 白名单。Scope 与工具对应关系（节选）：
| Scope | 可用的工具 |
|---|---|
| 任意有效 PAT | meta.whoami |
nezha:inventory:read |
server.list |
nezha:server:read |
server.get、fs.list、fs.read、fs.download_url |
nezha:server:exec |
server.exec |
nezha:server:write |
fs.write、fs.upload_url |
nezha:server:delete |
fs.delete |
建议最小权限：仅巡检用 nezha:inventory:read 与 nezha:server:read；需要远程执行再开 nezha:server:exec；写删文件再开 write/delete，并对高风险 scope 限制服务器白名单与有效期。官方说明见 Nezha MCP 指南 与 API Token（PAT）。
典型用法思路¶
配置完成且状态为已连接后，Agent 即可调用 mcp__nezha__* 工具。具体参数以 Nezha 返回的 inputSchema 为准。常见组合包括：
- 用
mcp__nezha__meta_whoami确认当前 Token 的 scope 与白名单。 - 用
mcp__nezha__server_list、mcp__nezha__server_get做资产与状态快照。 - 用
mcp__nezha__fs_list、mcp__nezha__fs_read读目录与小段日志。 - 在明确授权下使用
mcp__nezha__server_exec执行非交互式一次性命令（Nezha 侧默认超时 30 秒，最大 300 秒）。 - 大文件可用
mcp__nezha__fs_download_url/mcp__nezha__fs_upload_url生成一次性 URL（默认有效期约 300 秒，单文件上限 100 MiB）；需正确配置 Nezha 的dashboard_host。
工具列表随 Nezha 实例的 tools/list 变化，不同版本可能略有差异。
适用场景与注意¶
适合：已在用 Nezha V2 做监控，希望在 DSH Agent 中直接调用官方 MCP 能力、并希望通过 Web UI 管理端点与 PAT 的团队。
安全与运行方式：
- 生产环境使用 HTTPS；
server.exec与fs.write/fs.delete等属于高风险操作，应结合 DSH 工具权限与确认机制，并遵循最小 PAT scope。 - 插件在 DSH 进程权限下运行；安装前应查看仓库源码与 MIT 许可证，并保护好 profile 目录、备份与凭据存储。
- 不再使用时在 Nezha 撤销 PAT，并在插件设置页清除已保存令牌。
常见故障（细节见仓库 README）：401 多为 PAT 无效或误用 JWT；403 检查 scope 与白名单后 刷新工具；404 检查 enable_mcp、反向代理是否转发 POST /mcp；超时需同时调整插件超时与反向代理读超时；429 需注意 Nezha 对 Token 的限流（约每秒 10 次、每分钟 120 次）。
结尾¶
dsh-nezha 把哪吒 V2 内置 MCP 接到 DSH，用可视化配置完成端点与 PAT 管理，并把 Nezha 工具以 mcp__nezha__* 形式暴露给 Agent。社区目录页：https://www.skillhub.cn/plugins/kaecho/dsh-nezha；源码与完整故障排查：https://github.com/kaecho/dsh-nezha。
