Watchers
Harness-agent tools
本技能从 Octop 移植。使用以下 harness/deepagents 工具:
| 概念 | 工具 |
|---|---|
| Shell | execute |
| 读/写/编辑文件 | read_file, write_file, edit_file |
| 查找文件/搜索内容 | glob, grep |
| 获取 URL | web_fetch |
| 浏览器自动化 | browser_use |
| 子代理工作 | task |
| 记忆 | memory_store, memory_recall, memory_search |
内置技能文件位于 /_builtin_skills/<name>/。用户安装的技能位于 /skills/<name>/。
按间隔轮询外部源,仅对新项目做出反应。三个现成脚本加一个共享水位线助手;通过 cron 作业(或直接从终端)将它们接入。
何时使用
- 用户想要监视 RSS/Atom 源并在新条目时收到通知
- 用户想要监视 GitHub 仓库的 issues / PR / releases / commits
- 用户想要轮询任意 JSON 端点并在新项目时收到通知
- 用户询问"X 的监视器"或"当 X 变化时通知我"
心智模型
监视器只是一个脚本,它:
- 从外部源获取数据
- 与先前已见 ID 的水位线文件进行比较
- 将新水位线写回
- 向 stdout 打印新项目(或无更改时为空)
下面的脚本处理所有三个。代理通过 execute 工具运行它们——从 cron 作业、webhook 或交互式聊天中——并报告新内容。
现成脚本
所有三个脚本在技能安装后都位于 /_builtin_skills/watchers/scripts/。
| 脚本 | 监视内容 | 去重键 |
|---|---|---|
watch_rss.py |
RSS 2.0 或 Atom 源 URL | <guid> / <id> |
watch_http_json.py |
返回对象列表的任意 JSON 端点 | 可配置的 id 字段 |
watch_github.py |
GitHub issues / PR / releases / commits | id / sha |
所有三个脚本:
- 首次运行记录基线——从不重放现有源
- 水位线是 bounded ID 集合(最多 500 个)以限制内存
- 输出格式:
## <title>\n<url>\n\n<optional body>每个项目 - 无新项目时 stdout 为空——调用者将其视为静默
- 获取错误时非零退出
用法
通过 execute 运行监视器(路径相对于 init_workspace 后的工作区根目录):
python _builtin_skills/watchers/scripts/watch_rss.py \
--name hn --url https://news.ycombinator.com/rss --max 5
监视 GitHub 仓库(设置 GITHUB_TOKEN 环境变量以避免 60 次请求/小时的匿名速率限制):
python _builtin_skills/watchers/scripts/watch_github.py \
--name my-issues --repo owner/repo --scope issues
轮询任意 JSON API:
python _builtin_skills/watchers/scripts/watch_http_json.py \
--name api --url https://api.example.com/events \
--id-field event_id --items-path data.events
周期性运行
octop-harness 没有内置 cron。选项:
- 临时性——用户询问时运行监视器;如果 stdout 非空则总结
- OS cron / launchd——在主机上调度相同的
python _builtin_skills/watchers/scripts/...命令 - 外部调度器——将脚本接入你的部署的作业运行器
示例用户提示:
每当我询问时,运行 HN 监视器并总结新标题。如果 stdout 为空则保持静默。
状态文件
每个监视器将 watcher-state/<name>.json 写入磁盘。检查:
cat watcher-state/hn.json
强制重放(下次运行视为首次轮询):
rm watcher-state/hn.json
编写你自己的
所有三个脚本使用相同的模板:加载水位线、获取、diff、保存、输出。scripts/_watermark.py 是共享助手;导入它以获取原子写入 + bounded ID 集合 + 首次运行基线。有关它需要多少样板,请参见三个参考脚本中的任何一个。
常见陷阱
- 在每个 tick 打印"无新项目"头部。 调用者依赖空 stdout = 静默。如果你在空 delta 时打印任何内容,你就会垃圾邮件频道。已发布的脚本会处理此问题;自定义脚本也必须如此。
- 期望首次运行发出项目。 它不会——首次运行记录基线。如果你需要初始摘要,请在首次运行后删除状态文件,或在你自己的脚本中添加
--prime-with-latest N标志。 - unbounded 水位线增长。 共享助手上限为 500 个 ID。对于高流失率源,请提高它;对于受限文件系统,请降低它。
- 将状态目录放在代理无法写入的位置。 默认
watcher-state/在本地 backend 上是可写的。