前言¶
在 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。
| 角色 | 说明 |
|---|---|
| 调度 | 默认每 pollIntervalMs（10 秒）轮询一次到期的 watch |
| 唤醒 | checker 输出合法 JSON 且 notify: true 时才投递；同一轮同一 target 合并为一条消息 |
| 可观测 | 通过工具查看运行/通知/失败统计与会话 id |
| 契约 | 用户发送 /watch-reload 加载配置；checker 遵守 stdout JSON 契约 |
去重、重试、以及「只在变化时提醒」由 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 一致）：
| 字段 | 必需 | 说明 |
|---|---|---|
id |
是 | 1–64 字符、无空白，唯一标识 |
checker |
与 preset 二选一 |
非空 argv 数组，直接执行、不经 shell |
preset |
与 checker 二选一 |
目前仅 "mailbox"，映射到随包 mailbox checker |
cwd |
否 | 省略时用配置文件所在目录 |
interval |
否 | 秒，>0，默认 60 |
timeout |
否 | 秒，>0，默认 30 |
target |
否 | 会话 id；新 watch 省略时绑定执行 /watch-reload 的当前会话 |
enabled |
否 | 默认 true |
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：
- 方式 A：Web 侧边栏「插件」页（适合普通 Web 用户、少折腾）。
- 方式 B：已开 Creator 预设且具备
plugin_manager时，由 Agent 按 install.md 代装（会涉及 danger-full-access 或审批）。 - 方式 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
