whaojie797-design/source-watch

MIT
Python
Zero deps
CI

source-watch

为你的 Agent 所依赖的网页信源提供本地、确定性的变更监控。

本地的、确定性的「信源变更监控」工具：给 Agent 一份信源清单，init 建基线，check 精准报告「哪些信源变了、正文改了哪几段、是否命中你关心的关键词、哪些 404 了」。

demo

之前 / 之后

之前 —— 你的 Agent 引用了一个外部页面（库的更新日志、竞品定价、
API 文档、法规页面），却完全不知道它变了。它要么每次重新抓取整个嘈杂的页面
（慢，淹没在导航/广告/时间戳里），要么基于过时的上下文作答。

之后 —— 你维护一份 sources.yml。source-watch 会告诉 Agent 确切
变了什么，以它可解析的 diff 形式呈现，并把你关心的变更标记为 HIGH。
不用再猜页面是不是最新的了。

它能做什么

- init —— 为每个信源建立基线：降噪后的正文 + 标题 + 指纹。
- check —— 重新抓取，并将每个信源分类为 content / title / new / gone。
- 降噪 —— 剥离 script/style/nav/footer/header，可选 CSS selector，
默认取最长的文本块。
- 严重程度 —— 任何文本命中 watch 关键词/正则的变更都会被标记为 HIGH。
- 输出 —— WATCH_REPORT.md（给人看）+ watch-state.json（机器可读的基线和
最近一次报告，Agent 可以直接读取）。
- 对离线友好 —— 支持 file:// 信源和纯标准库的抓取器；零第三方
依赖。

安装

克隆到你的 Agent 的 skills 目录。无需 pip install。

Codex
git clone https://github.com/whaojie797-design/source-watch ~/.codex/skills/source-watch

Claude Code
git clone https://github.com/whaojie797-design/source-watch ~/.claude/skills/source-watch

Cursor
git clone https://github.com/whaojie797-design/source-watch ~/.cursor/skills/source-watch

快速开始

1. describe what to watch
cp sources.example.yml sources.yml
edit urls / selectors / watch keywords

2. baseline
python scripts/watch.py init --config sources.yml --store .watchstore

3. later: what changed?
python scripts/watch.py check --config sources.yml --store .watchstore

4. acknowledge the change and re-baseline
python scripts/watch.py check --config sources.yml --store .watchstore --update

sources.yml：
sources:
- name: next-changelog
url: https://nextjs.org/changelog
selector: "main article"
watch:
- "breaking"
- "deprecat"
- name: rival-pricing
url: https://example.com/pricing
watch: ["price", "plan"]

示例报告（真实）

$ python scripts/watch.py init --config sources.yml --store .ws
[BASE] next-changelog — 124 chars, fingerprint 2b299333df8099b6
[BASE] rival-pricing — 88 字符，指纹 7c1ae0b4f2c9d3e1
[BASE] acme-docs — 220 字符，指纹 9412af520f24141e
基线已保存：.ws/watch-state.json（3 个源）

$ python scripts/watch.py check --config sources.yml --store .ws
[HIGH] next-changelog — content — 匹配：breaking
[OK] rival-pricing — 未更改
[UNREACHABLE] acme-docs — 文件未找到：.../simple.html

已监视 3 个源 · 1 个已更改 · 1 个 HIGH · 1 个无法访问

WATCH_REPORT.md（摘录）：
HIGH
next-changelog — content
- url: file:///.../changelog.html
- 匹配：breaking
- 差异：
@@
- 修复：改进了静态资源的缓存。
+ 破坏性变更：移除了旧版配置格式，升级前请先迁移。

工作原理

1. 获取每个 url（http(s) 使用 urllib，file:// 直接读取）。
2. 使用 html.parser 提取正文文本，丢弃噪声标签；可选的 selector
缩小范围，若未匹配到任何内容则静默回退到完整文档。
3. 对规范化后的正文进行哈希 → fingerprint。与基线比较。
4. 对差异进行分类，若命中 watch 模式，则将严重级别提升为 HIGH。
5. 写入 WATCH_REPORT.md + 更新 watch-state.json（基线 + 上次报告）。

一切均为确定性且可离线运行；测试套件完全
针对本地 file:// 测试夹具运行。

局限性

- 它比较的是已获取、可提取的文本。纯粹通过
JavaScript 渲染内容的页面（无服务器端 HTML）需要预渲染快照，或在
静态标记上使用 selector。
- file:// 源非常适合离线文档和测试，但无法看到实时网站。
- “最长文本块”启发式是一个合理的默认值，并非完整的阅读器；在
噪声较多的页面上使用 selector 以提高精确度。
- watch 仅匹配新的正文文本（而非差异）——请保持模式具体明确。

许可证

MIT © 2026 whaojie797-design