前言¶

在 DeepSeek Harness 里跑长期任务时，常见做法是定时让 Agent 自己「看一眼」有没有新情况。这样要么浪费 token，要么把对话拉得很长。若把检查逻辑写成独立脚本，又缺少一个稳定、可配置的调度层，把「无事」和「有事」分开处理。

dsh-watch-kit-plugin（维护者 rokyaria，GitHub 仓库 rokyaria/dsh-watch-kit-plugin）是面向 DSH 的常驻巡检插件（当前资料版本 v0.3.1）：按配置的间隔运行 checker；checker 仅在需要处理时于 stdout 输出 notify: true，插件才把消息投递到绑定的会话；其余轮次不产生对话、不消耗 LLM token。运行时状态落在 SQLite，watch 列表来自用户级 $DSH_HOME（默认 ~/.dsh）下 watch/ 目录中的 JSON 配置。

这是什么¶

一句话：它是 DSH 内的 watch 调度器与事件唤醒层，不是 OS 通知、系统 cron 或独立 daemon。

去重、重试、以及「只在变化时提醒」由 checker 自行维护状态；checker 以当前用户身份执行，权限与普通 shell 相同，安装前应阅读源码与 MIT 许可证。

核心功能¶

配置与生效路径¶

watch 配置为单文件 JSON，默认路径为 <dshHome>/watch/watches.json。编辑后必须由用户本人在会话输入框发送 /watch-reload 才会同步进数据库；Agent 不能代发该 slash command。首次安装后不会自动导入配置文件，必须手动执行一次 /watch-reload。

数据库默认 <dshHome>/watch/watch.db。整份 watches.json 一起校验：任一条目非法则 reload 返回错误，数据库不变；文件中删除的 watch 软删除，重新出现即恢复。

watches.json 字段¶

顶层结构为 {"watches": [...]}。每个 watch 主要字段如下（与 README 一致）：

checker 契约¶

插件按 checker 数组 spawn 进程，设置环境变量 WATCH_ID、WATCH_INTERVAL、WATCH_TIMEOUT。stdout 必须是合法 JSON 对象；只认 stdout，退出码不参与「是否通知」的语义。

有事件时输出：

{"notify": true, "message": "摘要说明"}

无事时输出：

{"notify": false}

stdout 是唤醒信号，不是大数据通道：正文或大结果应写入文件，message 里放摘要与路径。默认 stdout 上限 64KiB，超限按 invalid_json 处理。最小示例如 README 中的 bash 脚本：检测目录是否有待处理文件，有则 notify: true。

随包 mailbox 扩展（可选）¶

extension/mailbox/ 提供 Python 3.9+ 邮箱 checker（标准库、无第三方依赖），在 watches.json 中用 preset: "mailbox"，无需手写 checker 路径。需单独准备 mail.env、allowlist 等；默认不通知任何人，必须配置 per-account allowlist；授权码不能写进 watches.json。细节见仓库内 extension/mailbox/README.md 与 skills/watch-mailbox/SKILL.md。

运行上限（可选）¶

并发检查数、stdout/stderr/message 字节上限、运行记录保留天数等，通过 profile 的 cordis.patch.yml 覆盖插件 Config 中的 limits 与 pollIntervalMs，不能按单条 watch 单独配置。修改 patch 后需 DSH 重新加载插件；watches.json 的变更仍只走 /watch-reload。

安装与启用¶

安装入口分三种，具体可复制步骤、验证清单与故障排查见仓库根目录 install.md：

1. 方式 A：Web 侧边栏「插件」页（适合普通 Web 用户、少折腾）。
2. 方式 B：已开 Creator 预设且具备 plugin_manager 时，由 Agent 按 install.md 代装（会涉及 danger-full-access 或审批）。
3. 方式 C：插件页不可用且没有 plugin_manager 时，按 install.md 手动兜底；若有受管 profile 仅插件页异常，可切 Creator 用方式 B。

资料中未给出统一的 dsh plugin add … 一行命令，请勿凭仓库名自行拼接。插件要求 Node.js >= 24.0.0、DSH ^0.2.1-rc.3（见 package.json）。

安装完成后，在 ~/.dsh/watch/watches.json 写好 watch，用户发送 /watch-reload。有事件时会收到 [WATCH 通知]；需要统计时可让 Agent 调用 watch_runs，查可用会话 id 用 watch_sessions。

典型用法¶

自定义 checker¶

1、新建配置文件（路径可随 DSH_HOME 变化，以下为默认）：

{
  "watches": [
    {
      "id": "mail-inbox",
      "checker": ["bash", "/abs/path/check-mail.sh"],
      "cwd": "/abs/path",
      "interval": 60,
      "timeout": 30,
      "enabled": true
    }
  ]
}

2、在 DSH 输入框发送 /watch-reload。

3、之后约每 60 秒运行一次 checker（调度器默认 10 秒轮询到期项）；当 stdout 为 {"notify":true,"message":"…"} 时，绑定会话收到一条 [WATCH 通知]。

mailbox preset 模板¶

启用前将 enabled 改为 true 并准备好 env 与 allowlist 文件，再 /watch-reload：

{
  "id": "mailbox-account-1",
  "preset": "mailbox",
  "enabled": false,
  "mailbox": {
    "envFile": "/absolute/path/to/mail.env",
    "stateDir": "~/.dsh/mailbox",
    "allowAccountFile": "/absolute/path/to/allow-accounts.json",
    "remindAfterMinutes": 30,
    "maxNotify": 20,
    "folder": "INBOX",
    "python": "python3"
  },
  "interval": 60,
  "timeout": 60
}

适用场景与注意¶

适合：需要在 DSH 会话内被动响应外部变化（邮件、构建产物、队列文件等），且希望检查逻辑与 Agent 对话解耦、无事零 token 的场景。

不适合：替代系统级 cron 或跨机器统一调度；也不提供 OS 级沙箱——checker 与 DSH 同用户权限，应对不可信输入时在 checker 或业务层自行防护。

多实例可共享 DB 以降低重复执行概率，但不保证跨实例通知去重。社区目录页 skillhub.cn 上的插件条目 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；分类为工作流类插件。

结尾¶

dsh-watch-kit-plugin 把「定时检查」和「唤醒 Agent」拆成两层：SQLite 记调度与运行事实，checker 用极简 JSON 决定是否打扰会话。配置集中在 watches.json，一次 /watch-reload 生效；需要邮箱场景时可选用随包 mailbox preset。

• 目录页：https://www.skillhub.cn/plugins/rokyaria/dsh-watch-kit-plugin
• 源码与文档：https://github.com/rokyaria/dsh-watch-kit-plugin