@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/devops/pinggy-tunnel/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: pinggy-tunnel
+description: 通过 Pinggy 使用 SSH 建立零安装的 localhost 隧道。
+version: 0.1.0
+author: Teknium (teknium1), Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Pinggy, Tunnel, Networking, SSH, Webhook, Localhost]
+    related_skills: [cloudflared-quick-tunnel, webhook-subscriptions]
+---
+
+# Pinggy Tunnel Skill
+
+使用 Pinggy SSH 反向隧道将本地服务（开发服务器、webhook 接收器、MCP 端点、演示）暴露到公共互联网。无需安装守护进程——用户自带的 SSH 客户端连接到 `a.pinggy.io:443`，Pinggy 会返回一个公共的 HTTP/HTTPS URL。
+
+免费版：60 分钟隧道，随机子域名，无需注册。专业版（$3/月）可选择使用 token。
+
+## 何时使用
+
+- 用户要求“将此本地服务公开”、“分享我的开发服务器”、“将此 URL 公开”、“ tunnel 端口 N”、“为 webhook 获取一个公开 URL”
+- 需要在本地任务期间接收 webhook 回调（Stripe, GitHub, Discord, AgentMail）
+- 与远程方共享一次性 HTTP 演示（MCP 服务器，Ollama/vLLM 端点，仪表板）
+- 主机具有 SSH 但没有 `cloudflared` / `ngrok` 二进制文件，并且安装它们过于繁琐
+
+如果主机已经配置了 `cloudflared`，优先使用 `cloudflared-quick-tunnel` skill —— Cloudflare 快速隧道不会在 60 分钟后过期。
+
+## 前置条件
+
+- PATH 中存在 `ssh` (`ssh -V`)。 默认在 Linux, macOS 和 Windows 10+ 上可用。无需其他安装。
+- 在隧道启动之前，本地服务需在 `127.0.0.1:<port>` 上监听。Pinggy 会返回 URL，但在本地源站启动之前，它们将返回 502。
+
+可选:
+
+- 用于付费 Pro 功能（持久子域名、自定义域名、多重隧道、无 60 分钟限制）的 `PINGGY_TOKEN` env var。免费版无需凭据。
+
+## 快速 参考
+
+```bash
+# Plain HTTP/HTTPS tunnel for port 8000 (free tier)
+ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 \
+    -R0:localhost:8000 free@a.pinggy.io
+
+# TCP tunnel (databases, raw SSH, etc.)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:5432 tcp@a.pinggy.io
+
+# TLS tunnel (Pinggy can't decrypt — bring your own certs at origin)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:443 tls@a.pinggy.io
+
+# Basic auth gate (b:user:pass)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "b:admin:secret+free@a.pinggy.io"
+
+# Bearer token gate (k:token)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "k:mysecrettoken+free@a.pinggy.io"
+
+# IP whitelist (w:CIDR)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "w:203.0.113.0/24+free@a.pinggy.io"
+
+# Enable CORS + force HTTPS redirect
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "co+x:https+free@a.pinggy.io"
+
+# Pro tier (persistent URL, no 60-min cap)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 "$PINGGY_TOKEN+a.pinggy.io"
+```
+
+## 流程 —— 启动隧道并获取 URL
+
+模型 SHOULD 使用 `terminal` 工具。隧道必须在共享期间保持活动状态，因此将其作为后台进程运行并从 stdout 解析公共 URL。
+
+### 1. 确认本地源站已启动
+
+```bash
+curl -sI http://127.0.0.1:8000/ | head -1
+# expect HTTP/1.x 200 (or any non-connection-refused response)
+```
+
+如果尚无任何程序在监听，请先启动它（例如 `python3 -m http.server 8000 --bind 127.0.0.1`）。Pinggy 会很乐意返回一个指向虚无的 URL —— 在源站启动之前，用户将看到 502。
+
+### 2. 将隧道作为后台进程启动
+
+使用 `terminal(background=True)` 并将输出捕获到日志文件中（Pinggy 在 stdout 上打印 URL，然后保持连接打开）：
+
+```bash
+LOG=/tmp/pinggy-8000.log
+nohup ssh -p 443 \
+    -o StrictHostKeyChecking=no \
+    -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -o ServerAliveCountMax=3 \
+    -R0:localhost:8000 free@a.pinggy.io \
+    > "$LOG" 2>&1 &
+echo $! > /tmp/pinggy-8000.pid
+```
+
+`StrictHostKeyChecking=no` + `UserKnownHostsFile=/dev/null` 会跳过首次运行的主机密钥提示。`ServerAliveInterval=30` 可防止 SSH 会话被空闲 NAT 切断。
+
+### 3. 从日志中解析出 URL
+
+```bash
+sleep 4
+grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-8000.log | head -1
+```
+
+预期输出如下所示：
+
+```
+You are not authenticated.
+Your tunnel will expire in 60 minutes.
+http://yqycl-98-162-69-48.a.free.pinggy.link
+https://yqycl-98-162-69-48.a.free.pinggy.link
+```
+
+将 `https://...pinggy.link` URL 交给用户。
+
+### 4. 验证
+
+```bash
+curl -sI https://<the-url>/ | head -3
+# expect 200/302/whatever the local origin actually returns
+```
+
+如果收到 `502 Bad Gateway`，说明 SSH 会话已建立，但本地源站未在监听 —— 请先修复步骤 1。
+
+### 5. Teardown
+
+```bash
+kill "$(cat /tmp/pinggy-8000.pid)"
+# or, if the pid file got lost:
+pkill -f 'ssh -p 443 .* free@a\.pinggy\.io'
+```
+
+如果你拥有来自 `terminal(background=True)` 的 session_id，优先使用 `process(action='kill', session_id=...)`。
+
+## 通过用户名关键字进行访问控制
+
+Pinggy 将控制标志堆叠到由 `+` 分隔的 SSH 用户名中。当包含 `+` 时，请始终将整个 `user@host` 参数用引号括起来：
+
+| 关键字 | 效果 |
+|---------|--------|
+| `b:user:pass` | HTTP Basic 认证门禁 |
+| `k:token` | Bearer-token 标头门禁 (`Authorization: Bearer <token>`) |
+| `w:CIDR` | IP 白名单（单个 IP 或 CIDR，可重复） |
+| `co` | 添加 `Access-Control-Allow-Origin: *` (CORS) |
+| `x:https` | 强制 HTTPS —— 自动将 HTTP 重定向到 HTTPS |
+| `a:Name:Value` | 添加请求标头 |
+| `u:Name:Value` | 更新请求标头 |
+| `r:Name` | 移除请求标头 |
+| `qr` | 将 URL 的二维码打印到 stdout（方便移动端分享） |
+
+自由组合：`"b:admin:secret+co+x:https+free@a.pinggy.io"`。
+
+## Web Debugger（可选）
+
+Pinggy 可以将入站流量镜像到 `localhost:4300` 进行检查。在 SSH 命令中添加本地转发：
+
+```bash
+ssh -p 443 -L4300:localhost:4300 -R0:localhost:8000 free@a.pinggy.io
+```
+
+然后在浏览器中打开 `http://localhost:4300` 以查看实时的请求/响应对。
+
+## 注意事项
+
+- **免费版有 60 分钟的硬性上限。** SSH 会话将在 60 分钟时终止；URL 将失效。若需更长时间的共享，请使用 `PINGGY_TOKEN` (Pro) 或使用 shell 循环自动重启（请注意，免费版每次重启时 URL 都会更改）。
+- **免费版 URL 是随机的，且在重启时会更改。** 不要将其加为书签，也不要将其粘贴到配置文件中。每次都要从日志中重新解析。
+- **并发的免费隧道限制为每个源 IP 一个。** 从同一台机器启动第二个隧道通常会杀死第一个隧道。Pro 版可解除此限制。
+- **用户名中的 `+` 必须加引号。** 直接使用 `ssh ... b:admin:secret+free@a.pinggy.io` 在 bash 中有效，但在将 `+` 特殊对待的 shell 中，或者在以编程方式组装时会出错。请务必用双引号括起来。
+- **不要在无访问控制标志的情况下对敏感内容进行隧道传输。** 直接使用 HTTP 隧道可能会被任何拥有 URL 的人访问。对于非公开服务，请使用 `b:`、`k:` 或 `w:`。
+- **`process(action='log')` 可能会丢失 SSH 横幅输出。** Pinggy 会打印 URL，随后 SSH 会话将变为交互式。请始终重定向到日志文件并直接 `grep` 该文件 —— 与 `cloudflared-quick-tunnel` 的模式相同。
+- **首次运行时的主机密钥提示。** 默认的 OpenSSH 配置会要求用户接受 Pinggy 的主机密钥。对于无人值守的运行，请务必传递 `-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null`。
+- **TCP 和 TLS 隧道返回的是 `<subdomain>.a.pinggy.online:<port>` 对，而不是 https URL。** 请使用不同的正则表达式（`tcp://` 和端口）进行解析。不要假设每个 Pinggy 隧道都是 HTTP。
+- **Pro 模式需要 token 作为用户名，而不是标志。** 使用 `"$PINGGY_TOKEN+a.pinggy.io"`（没有 `free@`）。使用 token 时，你还可以添加 `:persistent` 以获得稳定的子域名 —— 参见 `pinggy.io/docs/`。
+
+## 配方
+
+将本地源站与 Pinggy 隧道相结合的复合模式。每个配方都是独立的 —— 启动源站、启动隧道、解析 URL、将其交还给用户。
+
+### 配方 1 —— 接收 webhook 回调
+
+在以下情况使用 外部服务（Stripe、GitHub、Discord、AgentMail 等）需要在本地任务期间 POST 到可公开访问的 URL。
+
+```bash
+# 1. Tiny capturing server: every request gets appended to /tmp/webhook-hits.log
+cat >/tmp/webhook-server.py <<'PY'
+import http.server, json, datetime, pathlib
+LOG = pathlib.Path("/tmp/webhook-hits.log")
+class H(http.server.BaseHTTPRequestHandler):
+    def _capture(self):
+        n = int(self.headers.get("content-length") or 0)
+        body = self.rfile.read(n).decode("utf-8", "replace") if n else ""
+        rec = {"t": datetime.datetime.utcnow().isoformat(), "path": self.path,
+               "method": self.command, "headers": dict(self.headers), "body": body}
+        with LOG.open("a") as f: f.write(json.dumps(rec) + "\n")
+        self.send_response(200); self.send_header("content-type","application/json")
+        self.end_headers(); self.wfile.write(b'{"ok":true}\n')
+    def do_GET(self): self._capture()
+    def do_POST(self): self._capture()
+    def log_message(self,*a,**k): pass
+http.server.HTTPServer(("127.0.0.1", 18080), H).serve_forever()
+PY
+nohup python3 /tmp/webhook-server.py >/tmp/webhook-server.log 2>&1 &
+echo $! >/tmp/webhook-server.pid
+
+# 2. Tunnel — bearer-token-gate so randos can't pollute the capture log
+nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:18080 "k:$(openssl rand -hex 12)+free@a.pinggy.io" \
+    >/tmp/webhook-pinggy.log 2>&1 &
+echo $! >/tmp/webhook-pinggy.pid
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/webhook-pinggy.log | head -1)
+echo "Webhook URL: $URL"
+
+# 3. While the agent works, watch hits land
+tail -f /tmp/webhook-hits.log
+```
+
+将 `$URL` 交给需要调用你的服务。Teardown：`kill $(cat /tmp/webhook-server.pid) $(cat /tmp/webhook-pinggy.pid)`。
+
+### 配方 2 —— 通过 HTTP/SSE 暴露 MCP 服务器
+
+适用于 远程 MCP 客户端（另一台机器上的 Claude Desktop、队友的编辑器等）需要访问在本地机器上运行的 MCP 服务器。仅适用于使用 HTTP 传输的 MCP 服务器 —— 无法对 stdio 模式的服务器进行隧道传输。
+
+```bash
+# 1. Start the MCP server in HTTP mode (example: a FastMCP server on port 8765)
+nohup python3 my_mcp_server.py --transport http --port 8765 \
+    >/tmp/mcp-server.log 2>&1 &
+echo $! >/tmp/mcp-server.pid
+
+# 2. Tunnel with a bearer token — MCP traffic should not be open to the internet
+TOKEN=$(openssl rand -hex 16)
+nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:8765 "k:$TOKEN+free@a.pinggy.io" \
+    >/tmp/mcp-pinggy.log 2>&1 &
+echo $! >/tmp/mcp-pinggy.pid
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/mcp-pinggy.log | head -1)
+echo "MCP URL: $URL"
+echo "Bearer token: $TOKEN"
+```
+
+远程客户端使用 `Authorization: Bearer $TOKEN` 连接到 `$URL`。Hermes 原生的 MCP 客户端配置：`{"transport": "http", "url": "<URL>", "headers": {"Authorization": "Bearer <TOKEN>"}}`。
+
+### 配方 3 —— 暴露本地 LLM 端点（Ollama / vLLM / llama.cpp）
+
+与远程调用者（另一个 agent、手机、队友）共享本地模型。Ollama 监听在 `:11434`，vLLM 和 llama.cpp 通常在 `:8000`。
+
+```bash
+# Pre-req: the model server is already running on 127.0.0.1:11434 (Ollama default)
+TOKEN=$(openssl rand -hex 16)
+nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:11434 "k:$TOKEN+co+free@a.pinggy.io" \
+    >/tmp/llm-pinggy.log 2>&1 &
+echo $! >/tmp/llm-pinggy.pid
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/llm-pinggy.log | head -1)
+echo "Endpoint: $URL"
+echo "Token:    $TOKEN"
+
+# Verify
+curl -s "$URL/api/tags" -H "Authorization: Bearer $TOKEN" | head
+```
+
+`co` 启用 CORS，以便浏览器调用者可以访问该端点。如果是仅后端调用者，则去掉 `co`。对于兼容 OpenAI 的 vLLM/llama.cpp 端点，调用者使用带有 `Authorization: Bearer $TOKEN` 的 base URL `$URL/v1` —— 但请注意，Pinggy 不会在正文中剥离/替换任何内容，因此模型服务器本身看到的是 Pinggy 的 token；本地服务器应配置为忽略身份验证（它已经在 `127.0.0.1` 上了），并让 Pinggy 进行门禁控制。
+
+### 配方 4 —— 使用一次性密码共享开发服务器
+
+最快的“让队友体验我正在运行的应用程序”模式。随机密码，打印一次，Ctrl-C 即可终止。
+
+```bash
+PASS=$(openssl rand -base64 12 | tr -d '+/=' | head -c 12)
+echo "Dev server password: $PASS"
+ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:3000 "b:dev:$PASS+co+x:https+free@a.pinggy.io"
+# URL prints to the terminal. Share URL + password. Ctrl-C to tear down.
+```
+
+`b:dev:$PASS` 使用 HTTP Basic 验证对 URL 进行门禁控制。`x:https` 强制使用 TLS。`co` 为 SPA 前端添加 CORS。
+
+## 验证
+
+```bash
+# End-to-end: spin up a trivial origin, tunnel it, hit it, tear down
+python3 -m http.server 18000 --bind 127.0.0.1 >/tmp/origin.log 2>&1 &
+ORIGIN_PID=$!
+
+nohup ssh -p 443 \
+    -o StrictHostKeyChecking=no \
+    -o UserKnownHostsFile=/dev/null \
+    -R0:localhost:18000 free@a.pinggy.io >/tmp/pinggy-verify.log 2>&1 &
+SSH_PID=$!
+
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-verify.log | head -1)
+echo "URL: $URL"
+curl -sI "$URL/" | head -1
+
+kill "$SSH_PID" "$ORIGIN_PID"
+```
+
+预期：一个 `pinggy.link` URL 并且 curl 头返回 `HTTP/2 200`。

package/extensions/skills/optional/devops/watchers/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: watchers
+description: 轮询 RSS、JSON API 和 GitHub，并带有 watermark 去重功能。
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos]
+metadata:
+  hermes:
+    tags: [cron, polling, rss, github, http, automation, monitoring]
+    category: devops
+    requires_toolsets: [terminal]
+    related_skills: []
+---
+
+# Watchers
+
+定时轮询外部数据源，并仅对新增条目做出响应。提供三个现成脚本以及一个共享的 watermark 辅助工具；你可以将它们接入 cron job（或直接从终端临时运行）。
+
+## 何时使用
+
+- 用户想要关注 RSS/Atom feed 并接收新条目的通知
+- 用户想要关注 GitHub repo 的 issues / pulls / releases / commits
+- 用户想要轮询任意的 JSON endpoint 并在新条目出现时收到通知
+- 用户要求“为 X 设置一个 watcher”或“当 X 发生变化时通知我”
+
+## 核心理念
+
+一个 watcher 本质上只是一个脚本，它会：
+
+1. 从外部数据源获取数据
+2. 与记录了已见 ID 的 watermark 文件进行比对
+3. 写入新的 watermark
+4. 将新条目输出到 stdout（如果没有变化，则什么都不输出）
+
+下面的脚本包揽了这三步。Agent 会通过终端工具运行它们（无论是来自 cron job、webhook 还是交互式聊天），并报告新增的内容。
+
+## 现成脚本
+
+安装该 skill 后，这三个脚本都会存放在 `$HERMES_HOME/skills/devops/watchers/scripts/` 中。每个脚本都会根据 `--name` 参数作为键，从 `WATCHER_STATE_DIR`（默认为 `$HERMES_HOME/watcher-state/`）读取其状态文件。
+
+| 脚本 | 监控内容 | 去重键 (Dedup key) |
+| --- | --- | --- |
+| `watch_rss.py` | RSS 2.0 或 Atom feed URL | `<guid>` / `<id>` |
+| `watch_http_json.py` | 任何返回对象列表的 JSON endpoint | 可配置的 id field |
+| `watch_github.py` | 某个 repo 的 GitHub issues / pulls / releases / commits | `id` / `sha` |
+
+这三个脚本都具有以下特性：
+
+- 首次运行只记录基准线 (baseline)，绝不重播现有的 feed
+- watermark 是一个有界的 ID 集合（最多 500 个），以限制内存占用
+- 输出格式：每个条目输出 `## <title>\n<url>\n\n<optional body>`
+- 没有新内容时 stdout 为空，调用者会将其视为静默状态
+- 获取数据出错时以非零状态码退出
+
+## 用法
+
+直接通过终端工具运行 watcher：
+
+```bash
+python $HERMES_HOME/skills/devops/watchers/scripts/watch_rss.py \
+  --name hn --url https://news.ycombinator.com/rss --max 5
+```
+
+关注 GitHub repo（在 `${HERMES_HOME:-~/.hermes}/.env` 中设置 `GITHUB_TOKEN` 以避免 60 次请求/小时的匿名速率限制）：
+
+```bash
+python $HERMES_HOME/skills/devops/watchers/scripts/watch_github.py \
+  --name hermes-issues --repo NousResearch/hermes-agent --scope issues
+```
+
+轮询任意的 JSON API：
+
+```bash
+python $HERMES_HOME/skills/devops/watchers/scripts/watch_http_json.py \
+  --name api --url https://api.example.com/events \
+  --id-field event_id --items-path data.events
+```
+
+## 接入 cron
+
+你可以使用类似以下的提示让 agent 安排一个 cron job：
+
+> 每 15 分钟运行一次 `watch_rss.py --name hn --url https://news.ycombinator.com/rss`。如果打印了任何内容，请总结这些标题并发送。如果没有打印任何内容，则保持静默。
+
+Agent 会在 cron job 的 agent loop 中通过终端工具调用该脚本；无需对 cron 内置的 `--script` 标志进行任何更改。
+
+## 状态文件
+
+每个 watcher 都会写入 `$HERMES_HOME/watcher-state/<name>.json`。查看内容：
+
+```bash
+cat $HERMES_HOME/watcher-state/hn.json
+```
+
+强制重播（下一次运行将被视为首次轮询）：
+
+```bash
+rm $HERMES_HOME/watcher-state/hn.json
+```
+
+## 编写你自己的脚本
+
+这三个脚本都使用相同的模板：加载 watermark、获取数据、比对差异、保存、输出。`scripts/_watermark.py` 是共享的辅助工具；导入它即可免费获得原子写入、有界 ID 集合以及首次运行基准线功能。你可以查看这三个参考脚本中的任意一个，了解所需的样板代码有多么少。
+
+## 常见陷阱
+
+1. **每次轮询都打印 "no new items" 标题。** 调用者依赖空 stdout 来判定为静默状态。如果你在没有新增内容时输出了任何信息，就会导致频道被刷屏。内置脚本已经处理了这个问题，自定义脚本也必须这样做。
+2. **期望首次运行就能输出条目。** 这是不可能的——首次运行只负责记录基准线。如果你需要初始摘要，请在首次运行后删除状态文件，或者在你自己的脚本中添加 `--prime-with-latest N` 标志。
+3. **无限制的 watermark 增长。** 共享辅助工具将其限制在最多 500 个 ID。对于高频更新的 feed 可以适当提高限制；在存储受限的文件系统上则应降低限制。
+4. **将状态目录放在 agent sandbox 无法写入的位置。** `$HERMES_HOME/watcher-state/` 始终是可写的。Docker/Modal 后端可能无法识别任意宿主机路径。

package/extensions/skills/optional/devops/watchers/scripts/_watermark.py

@@ -0,0 +1,148 @@
+"""Shared watermark helper used by the three watcher scripts.
+
+A watermark is just a JSON file that records the IDs we've seen on previous
+runs, so the next run only emits items we haven't seen before.
+
+Contract:
+- First run: record all IDs from the fetched batch, emit nothing.
+- Subsequent runs: emit items whose ID isn't in the stored set.
+- Bounded: keep at most `max_seen` IDs (default 500).
+- Atomic: write to a .tmp file and rename, so a crashed script can't
+  leave a half-written state file that permanently breaks dedup.
+
+Import and use from any custom watcher script:
+
+    from _watermark import Watermark
+
+    wm = Watermark.load("my-feed-name")
+    new_items = wm.filter_new(fetched_items, id_key="id")
+    wm.save()
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+
+def _state_dir() -> Path:
+    """Where watermark files live — respects WATCHER_STATE_DIR override."""
+    override = os.environ.get("WATCHER_STATE_DIR")
+    if override:
+        return Path(override)
+    # 默认值：$HERMES_HOME/watcher-state/，回退到 ~/.hermes/watcher-state/。
+    hermes_home = os.environ.get("HERMES_HOME") or str(Path.home() / ".hermes")
+    return Path(hermes_home) / "watcher-state"
+
+
+class Watermark:
+    """Per-watcher state. Persisted to <state_dir>/<name>.json."""
+
+    def __init__(self, name: str, *, max_seen: int = 500) -> None:
+        if not name or not name.replace("-", "").replace("_", "").isalnum():
+            raise ValueError(
+                f"watermark name must be alphanumeric + '-'/'_' (got {name!r})"
+            )
+        self.name = name
+        self.max_seen = max_seen
+        self._path = _state_dir() / f"{name}.json"
+        self._data: Dict[str, Any] = {"seen_ids": [], "first_run": True}
+
+    @classmethod
+    def load(cls, name: str, *, max_seen: int = 500) -> "Watermark":
+        wm = cls(name, max_seen=max_seen)
+        if wm._path.exists():
+            try:
+                wm._data = json.loads(wm._path.read_text(encoding="utf-8"))
+                wm._data.setdefault("seen_ids", [])
+                wm._data["first_run"] = False
+            except (OSError, json.JSONDecodeError):
+                # 状态文件损坏 —— 视作首次运行，但不崩溃。
+                wm._data = {"seen_ids": [], "first_run": True}
+        return wm
+
+    @property
+    def is_first_run(self) -> bool:
+        return bool(self._data.get("first_run", True))
+
+    @property
+    def seen(self) -> List[str]:
+        return list(self._data.get("seen_ids", []))
+
+    def filter_new(
+        self, items: Iterable[Dict[str, Any]], *, id_key: str = "id"
+    ) -> List[Dict[str, Any]]:
+        """Return items whose id isn't in the stored set.
+
+        Side effect: updates the in-memory seen set with every id in the
+        batch (so save() persists the full new watermark).  On first run,
+        records every id but returns an empty list (baseline, no replay).
+        """
+        existing = set(str(x) for x in self._data.get("seen_ids", []))
+        was_first_run = self.is_first_run
+
+        new_items: List[Dict[str, Any]] = []
+        batch_ids: List[str] = []
+        for item in items:
+            ident = item.get(id_key)
+            if ident is None:
+                continue
+            ident_str = str(ident)
+            batch_ids.append(ident_str)
+            if ident_str in existing:
+                continue
+            if was_first_run:
+                continue  # 记录但不触发
+            new_items.append(item)
+
+        combined = list(existing) + [i for i in batch_ids if i not in existing]
+        if len(combined) > self.max_seen:
+            combined = combined[-self.max_seen:]
+        self._data["seen_ids"] = combined
+        self._data["first_run"] = False
+        return new_items
+
+    def save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(".tmp")
+        tmp.write_text(
+            json.dumps(self._data, indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+        os.replace(tmp, self._path)
+
+
+def format_items_as_markdown(
+    items: List[Dict[str, Any]],
+    *,
+    title_key: str = "title",
+    url_key: str = "url",
+    body_key: Optional[str] = None,
+    max_body_chars: int = 500,
+) -> str:
+    """Render a list of items as Markdown for cron delivery.
+
+    One heading per item + its URL + optional snippet of body.  Output is
+    empty string when items is empty — cron will then treat stdout as
+    silent and skip delivery (existing behavior).
+    """
+    if not items:
+        return ""
+    lines: List[str] = []
+    for item in items:
+        title = (item.get(title_key) or "(no title)").strip()
+        url = (item.get(url_key) or "").strip()
+        lines.append(f"## {title}")
+        if url:
+            lines.append(url)
+        if body_key:
+            body = (item.get(body_key) or "").strip()
+            if body:
+                if len(body) > max_body_chars:
+                    body = body[:max_body_chars].rstrip() + "…"
+                lines.append("")
+                lines.append(body)
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"