前言¶
在 DSH 开发中，修改配置、主机代码或前端资源后，通常需要重启才能生效。这种“改了没反应”或“必须重启”的情况容易打断开发思路，且排查原因往往需要人工介入。本文介绍 dsh-plugin-debugging 插件，它为 DSH 智能体提供了运行时诊断与就地修复的能力，让智能体可以自主检查环境状态并执行修复操作。
插件定位¶
dsh-plugin-debugging 是由 dsh-plugin-lab 维护的插件。它旨在解决 DSH 插件开发中的运行时调试问题，让智能体能够自检自修其身处的运行时环境。
核心功能¶
安装后，智能体获得一组工具和技能文档。这些工具分为只读诊断和状态变更两类：
- dsh_list_instances
列出当前机器上运行的 DSH 主机。仅探测本地端口。 - dsh_check_auth
区分服务“未运行”与“未认证”两种状态。 - dsh_diagnose_plugin_load
检查插件是否成功加载，包括 bundle 成员、挂载形式和 loader 树。 - dsh_check_effect_mode
探测当前运行 profile，判断修改是立即生效、需要重启还是需要热重载。 - dsh_dump_config
显示 profile 解析后的配置树及诊断信息。 - dsh_sign_cookie
为浏览器会话 cookie 签名，使脚本或 CLI 客户端能够访问 DSH 实例。 - dsh_hot_reload
将挂载的 entry 交换到磁盘上的最新代码，失败时自动回滚，无需重启。 - dsh_restart
在真正需要时重启主机。（注意：此功能默认关闭）。
安装与启用¶
插件支持通过 npm 或源码安装。
- 通过 npm 安装
使用官方插件管理命令添加插件：
dsh plugin --profile web add dsh-plugin-debugging
- 从源码安装
如果需要修改或调试插件源码：
git clone https://github.com/dsh-plugin-lab/dsh-plugin-debugging.git
cd dsh-plugin-debugging
pnpm install && pnpm run build
dsh plugin --profile web add "$PWD"
前置要求：
* Node.js 版本 >= 20
* DSH 版本需满足 package.json 中定义的版本范围
注意事项：
* 不要跳过 pnpm install，否则可能导致依赖缺失。
* 安装后需要重启 dsh --profile web 才能生效。
典型用法¶
安装完成后，智能体可以通过斜杠命令调用技能。以下是常见操作场景：
- 检查生效模式
在修改配置或代码后，使用dsh_check_effect_mode检测当前环境，决定是使用热重载还是需要重启。 - 热重载代码
使用dsh_hot_reload交换代码，避免进程中断。 - 强制重启
当确认需要重启时，使用dsh_restart（需确保功能已开启）。
适用场景与安全边界¶
该插件适用于需要频繁调整配置、插件逻辑或前端资源的开发场景。使用时需注意以下几点安全与行为边界：
- 权限限制：除
dsh_restart外，其他工具均不会重启进程、重写配置文件或向主机数据目录写入内容。唯一例外是插件自身的命名空间。 - 默认行为：
dsh_restart功能默认是关闭的，使用前需确认配置。 - 认证状态：
dsh_check_auth返回 401 并不总是意味着会话过期。无 cookie 的请求会被拒绝，需在浏览器中验证服务状态。 - 热重载限制：
dsh_hot_reload可能导致资源泄漏（如未跟踪的定时器或 socket）。
总结¶
dsh-plugin-debugging 通过提供运行时诊断与修复工具，降低了 DSH 插件开发的调试成本。它让智能体具备了自我检查和自我修复的能力，是提升开发效率的有效手段。
- GitHub 仓库：https://github.com/dsh-plugin-lab/dsh-plugin-debugging
