前言¶

在 DeepSeek Harness（DSH）里，智能体已经可以通过定时任务（时钟）和 HTTP webhook 被唤醒。这两种方式都解决不了会话进行中的另一类情况：对话之外有人或进程改动了文件——构建结束、格式化工具重写目录树、测试产出报告、下载落盘、同事往共享目录里推了内容。若智能体不主动去看，往往要等到下一轮才察觉。

dsh-folderwatch 面向「监视目录并在变化时通知智能体」这一工作流。目录树发生变化时，智能体收到的是一份可执行的变更清单（创建、修改、删除及文件大小），并可选择立即唤醒（wake）或在下一步再处理（queue）。同时，本会话内由工具调用写入的路径会在短窗口内被记为「自身写入」，从通知中过滤，避免「写文件 → 被唤醒 → 再读自己刚写的文件」以及由构建/格式化/测试持续写盘造成的唤醒循环。

下面介绍插件定位、设计要点、安装配置与典型用法。事实以 GitHub 仓库 README 为准；社区目录页：skillhub 插件条目。

这是什么¶

• 名称：dsh-folderwatch（维护者：11111353535）
• 分类：工作流
• 一句话：Arm a directory against the agent that armed it；树变化时给出精确变更说明，并可唤醒智能体或排队注入消息。
• 版本（package.json）：0.1.0；许可证：MIT；运行时：Node ^22.19.0 || >=24.0.0

插件不声明 dsh-* 对等依赖，仅使用 node:* 以及 @deepseek-ai/dsh-tools、@deepseek-ai/dsh-llm、@deepseek-ai/schemastery，由 Harness 自身安装解析。

与「裸 fs.watch + 回调」的差别¶

README 归纳了三条设计，决定它能否长期挂着用，而不是当天下午就卸掉。

1. 快照与 diff，而非原始事件¶

fs.watch 只说明「有变化」，说不清改了什么；在 Windows 上可能双发、有时没有文件名、高负载下会丢事件。本插件对目录做快照并 diff，在各平台上正确归类重命名、删除和突发变更，并附带文件大小。fs.watch 仅作「尽快重扫」的提示；周期性重扫才是正确性路径。

2. Echo suppression（过滤本会话写入）¶

监视智能体正在编辑的目录时，典型失败模式是：智能体写了 src/app.ts，监视器触发，智能体被告知该文件变了再去读——若构建、格式化或测试由智能体自己拉起并持续写盘，会反复唤醒、浪费 token。

因此，命名了文件的工具调用会记入短生命周期账本；窗口内这些路径的变更记为 suppressed 而非投递。窗口故意很短（echoWindowMs，默认 2500ms）：十分钟前由智能体写的文件此刻再变，仍算真实外部变化。每批通知会写明过滤了多少条，便于区分「无事发生」与「是智能体自己写的」。

3. 投递模式可按监视单独选择¶

可随时打断的监视器很难长期开着；queue 只需一个参数，适合整段会话挂着监视而不交出打断权。

通知示例（README）：

[folderwatch] 3 changes under /work/shop/reports
watch: reports · 14:02:11
1 created · 1 modified · 1 deleted
  + /work/shop/reports/run-42.json  18KB
  ~ /work/shop/reports/latest.json  18KB
  - /work/shop/reports/run-41.json
(4 events suppressed as this session's own writes)

Read the new report and summarise what failed.

安装与配置¶

安装¶

从 Git 托管安装：

dsh plugin add https://github.com/11111353535/dsh-folderwatch

若从本地检出目录安装，传入绝对路径：

dsh plugin add /absolute/path/to/dsh-folderwatch

Profile 级配置¶

安装器会在 ~/.dsh/profiles/<profile>/cordis.patch.yml 插入一行；可按 profile 增加 config 块，例如：

- insert:
    - id: folderwatch
      name: 'dsh-folderwatch'
      config:
        quietMs: 400
        cooldownMs: 5000
        watches:
          - path: E:/work/reports
            label: reports
            pattern: '**/*.json'
            prompt: Read the new report and summarise what failed.
            mode: wake

工具与斜杠命令¶

folderwatch_add¶

Armed 一个监视。参数要点：

folderwatch_list¶

列出各 watch 状态、触发次数、是否有待投递变更。

folderwatch_check¶

立即重扫并报告自上次扫描以来的变化，不投递消息；适合在本轮内回答「有没有新东西」而不等待被唤醒。

folderwatch_fire¶

不等 quiet 周期，立即投递该 watch 的待处理变更；无待处理则说明且不发送。

folderwatch_remove¶

Disarm 并释放文件系统句柄；汇总 armed 期间投递批次数与被过滤的自身写入。

Slash command¶

/watch                                              # 清单
/watch add ./reports --pattern '**/*.json'          # armed，wake
/watch add ./build --queue                          # armed，下一轮注入
/watch add ./inbox --once                           # 首次投递后 disarm

（README 中斜杠命令一节在抓取资料处截断；以上行为以已列出的子命令为准。）

典型用法思路¶

1. 在会话中让智能体对报告目录、构建输出或共享 inbox 执行 folderwatch_add（或 /watch add），配上 pattern 与 prompt，说明变化后希望它做什么。
2. 若不希望外部写盘打断当前推理，对同一目录使用 mode: queue 或 --queue。
3. 长任务跑完后可用 folderwatch_check 主动看一眼 diff，或用 folderwatch_fire 验证投递链路。
4. 会话结束前 folderwatch_list / folderwatch_remove 清理 armed 的 watch。

适用场景与注意¶

适合：构建/测试/格式化在目录树落结果、下载或同事写入共享文件夹、需要「变化 + 具体 diff + 可选唤醒」的中会话自动化。

注意：

• 插件以当前 DSH 进程权限访问文件系统；安装前请自行审阅 源码 与 MIT 许可证。
• 社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」思路，本插件是工作流类扩展之一。
• 星标与版本以仓库与目录页实时信息为准；撰写时 GitHub 星标为 0。

结尾¶

dsh-folderwatch 补的是「会话中途、对话外改文件」这条唤醒路径：快照 diff 保证可读变更清单，echo suppression 避免智能体被自己拉起的写盘循环吵醒，投递模式在 wake 与 queue 之间可选。安装使用官方命令 dsh plugin add https://github.com/11111353535/dsh-folderwatch 即可接入。

• 目录页：https://www.skillhub.cn/plugins/11111353535/dsh-folderwatch
• GitHub：https://github.com/11111353535/dsh-folderwatch