前言¶

在 DSH 的智能体工作流里，dsh web 经常是本地开发、测试和 agent 协作的服务入口。手动在前台启动 dsh web 有一个明显问题：终端关闭、进程异常退出、机器睡眠唤醒之后，服务可能不再可用；如果需要在多个会话里稳定访问本地 web 服务，就得反复确认端口、进程和日志状态。

dsh-daemon 解决的就是这件事：把 dsh web 注册为一个自启动、自愈的后台服务。下面介绍它的能力、安装方式、典型命令，以及部署时需要注意的权限和升级事项。

这是什么¶

dsh-daemon 是一个 DSH 插件，用于将 DeepSeek Harness 的网络服务 dsh web 注册为后台服务。它不是直接替代 dsh web，而是在其外围生成一个 watchdog 脚本，并按平台注册系统级服务来保持 watchdog 运行。

本次资料中可核实的包信息如下：

• 仓库路径：chenkai2/dsh-daemon
• npm 包名：@chenkai114/dsh-daemon
• 版本：0.1.20
• 许可证：MIT
• Node 要求：>=18

peerDependencies 要求：

@deepseek-ai/cordis >=3
@deepseek-ai/dsh-tools >=0.1.0-rc.6

它的主要价值在于：安装后，dsh web 可以按用户级服务启动，在异常退出、睡眠唤醒、进程不可用等场景下，由 watchdog 按策略恢复。

核心能力¶

平台服务注册¶

dsh-daemon 支持不同平台的服务注册方式：

• macOS：LaunchAgent，使用 RunAtLoad 与 KeepAlive
• Linux：systemd user service；systemd 不可用时回退 cron @reboot
• Windows：VBS + 计划任务；资料标注尚未在真实 Windows 机器上验证

其中，Windows 行为目前只能按“已实现但未在真实机器验证”理解，不建议在未验证环境里直接当作生产可用能力。

watchdog 自愈¶

安装后，插件会生成一个独立的 watchdog 脚本。该脚本不依赖当前 DSH 会话，运行在用户级服务管理之下。

已核实的 watchdog 行为包括：

• 每 30 秒进行一次健康检查
• 连续 3 次健康检查失败后重启服务
• 睡眠唤醒后自动重启服务
• watchdog 是独立生成的脚本，不依赖当前会话
• 维护 $DSH_HOME/daemon/ 下的状态文件与日志

默认被检查的健康地址为：

http://127.0.0.1:<port>/health

端口解析顺序为：当前监听的 webServer 端口（通常 3080），其次 DSH_WEB_PORT，再其次工具显式 port 参数。

工具与 CLI¶

插件注册 7 个 dsh_daemon_* 工具，可供 agent 调用：

• dsh_daemon_install
• dsh_daemon_uninstall
• dsh_daemon_reinstall
• dsh_daemon_status
• dsh_daemon_start
• dsh_daemon_stop
• dsh_daemon_update

同时，安装过程会生成一个轻量 CLI：dsh-daemon。终端中可使用以下命令：

dsh-daemon status
dsh-daemon restart
dsh-daemon start
dsh-daemon stop
dsh-daemon update
dsh-daemon install
dsh-daemon uninstall
dsh-daemon reinstall
dsh-daemon help

其中，dsh-daemon restart 和 dsh-daemon stop 会中断所有打开的会话；如果直接拉起失败，watchdog 会在后续健康周期中重新拉起 web 服务。

自动更新¶

watchdog 会按配置检查 npm registry，并尝试更新同 major 版本。

已核实的更新策略：

• 同 major 版本可以自动更新
• major 版本变更不会自动更新，需要人工执行 dsh_daemon_update
• 自动更新模式支持 restart 和 download

restart 模式下，watchdog 会在下载完成后等待安静窗口，再重启 dsh web。
download 模式下，新包安装到 profile 并写入待生效标记，下次自然重启 dsh web 时生效。

安装与启用¶

安装前需要确认 PATH 中已经有 pnpm。如果没有，可以先启用：

corepack enable

下面介绍正式安装步骤。

1、安装插件到 web profile¶

使用官方插件安装命令，把包安装到 web profile：

dsh plugin --profile web add @chenkai114/dsh-daemon

这一步会把包安装到 web profile 的依赖目录中。仅全局安装不一定能被 loader 解析到，因为 profile 内依赖是更直接的解析路径。

2、重启 dsh web¶

安装完成后，重启 dsh web，让插件 bundle 生效。

3、让 agent 运行 dsh_daemon_install¶

在重启后的会话中，让 agent 执行：

dsh_daemon_install

该工具会生成 watchdog 脚本、状态文件，并按平台写入服务注册，然后启动 watchdog。

4、检查安装状态¶

安装完成后，可以用 agent 工具检查：

dsh_daemon_status

也可以用 CLI 检查：

dsh-daemon status

状态信息包括安装状态、端口、本地/最新版本、更新状态、watchdog PID、服务健康、最近日志等。

典型用法¶

安装后常用 agent 工具¶

在 agent 会话中，可以使用以下工具：

dsh_daemon_status
dsh_daemon_start
dsh_daemon_stop
dsh_daemon_reinstall
dsh_daemon_update

如果更换端口，使用：

dsh_daemon_reinstall

如果升级到包含新 watchdog 更新逻辑的版本后，也建议运行一次：

dsh_daemon_reinstall

这样可以按当前配置重新生成 watchdog 脚本。

终端 CLI 用法¶

终端中可以直接使用：

dsh-daemon status

查看当前 daemon 状态。

立即重启 dsh web：

dsh-daemon restart

启动或恢复服务：

dsh-daemon start

停止托管服务：

dsh-daemon stop

检查或应用更新：

dsh-daemon update

注册、卸载、重装类命令：

dsh-daemon install
dsh-daemon uninstall
dsh-daemon reinstall
dsh-daemon help

插件升级¶

升级时使用：

dsh plugin --profile web update @chenkai114/dsh-daemon

升级后重启 dsh web。

从旧版本升级的注意事项¶

如果从 v0.1.8 及更早版本升级，之前可能在 ~/.dsh/profiles/web/cordis.patch.yml 中手动添加过类似：

- insert: dsh-daemon

升级后必须删除这一行，但保留文件里的其他内容。否则 bundle 层和手动层会插入同一个 loader entry，导致 dsh web 启动时报：

duplicate loader entry id: dsh-daemon

删除后重启 dsh web 即可。

自动更新相关配置¶

以下环境变量会参与 watchdog 行为。它们的具体值可以在安装或重装时纳入生成脚本。

DSH_DAEMON_AUTO_UPDATE
DSH_DAEMON_UPDATE_INTERVAL
DSH_DAEMON_UPDATE_MODE
DSH_DAEMON_QUIET_WINDOW
DSH_DAEMON_DEFER_MAX
DSH_DAEMON_NPM_REGISTRY
DSH_DAEMON_PROFILE
DSH_DAEMON_HEALTH_INTERVAL
DSH_DAEMON_OPEN_BROWSER
DSH_DAEMON_CLI_DIR
DSH_DAEMON_NO_SYSTEM
DSH_DAEMON_TRUSTED_HOST

其中几个关键项：

• DSH_DAEMON_AUTO_UPDATE：是否启用自动更新检查
• DSH_DAEMON_UPDATE_MODE：自动更新模式，可为 restart 或 download
• DSH_DAEMON_HEALTH_INTERVAL：watchdog 健康检查间隔
• DSH_DAEMON_NPM_REGISTRY：检查与更新使用的 npm registry
• DSH_DAEMON_PROFILE：插件所在 profile 目录

适用场景与注意¶

这个插件适合需要长期运行 dsh web 的 DSH 使用者，尤其是：

• 希望在登录或系统启动后自动拉起 dsh web
• 希望进程异常退出后能自动恢复
• 需要统一查看状态、日志、更新状态
• 需要在 agent 会话中直接管理 daemon
• 需要在终端中不打开 GUI 也能控制服务

部署前需要注意以下几点。

权限¶

该插件对文件与命令操作会请求 danger-full-access。它会处理用户级系统服务、$DSH_HOME/daemon/ 下的状态文件，以及生成 watchdog 脚本。

如果部署环境拒绝提权，相关工具会以沙箱拒绝失败。因此安装前应检查源码与许可证，并确认该权限范围符合团队要求。

会话中断¶

restart 和 stop 会中断所有打开的会话。执行这些操作前，应先确认当前没有正在进行的重要对话或任务。

Windows 支持状态¶

Windows 支持资料中明确标注尚未在真实 Windows 机器上验证。若你的环境主要在 Windows 上使用，建议先在测试环境中验证登录时启动、计划任务、VBS 启动器和日志行为。

major 版本更新¶

major 版本变更不会自动更新。需要人工执行：

dsh_daemon_update

依赖要求¶

插件要求 Node >=18，并依赖：

@deepseek-ai/cordis >=3
@deepseek-ai/dsh-tools >=0.1.0-rc.6

安装到 web profile 时，还需要 PATH 中有 pnpm，可通过 corepack enable 启用。

结尾¶

dsh-daemon 的价值在于把 dsh web 从“手动前台服务”变成“用户级后台服务”：登录或系统启动后可自动拉起，异常退出后可按 watchdog 策略恢复，并提供 agent 工具与终端 CLI 两套管理入口。

对于需要稳定使用 dsh web 的 DSH 开发者，它可以减少手动启停、端口检查、日志确认和异常恢复的重复操作。

仓库地址：

https://github.com/chenkai2/dsh-daemon