literature-watch

定时文献监控 blueprint：每周按用户给定的主题、作者、DOI 清单查询 OpenAlex 与 Crossref，跨周去重后只报告新增作品。配套脚本 scripts/watch.py 负责网络查询与状态管理。

When to Use

• 用户要求"每周帮我盯一下某主题的新论文"
• 用户要求跟踪某位作者（OpenAlex author id）的新作
• 用户要求盯某几篇论文的新引用者
• 安装后 Hermes 把它登记为建议排程（suggested cron），用户接受后每周自动运行

安装与排程配置

本技能 frontmatter 带 metadata.hermes.blueprint，安装时 不会 静默创建定时任务，而是进入建议队列：

hermes skills install xngg1021/academic-research-kernel/skills/literature-watch
# 然后在会话中：
/suggestions             # 查看待处理建议
/suggestions accept N    # 接受并创建 cron 任务
/suggestions dismiss N   # 不再提示

默认排程 "0 9 * * 1"（每周一 09:00），deliver: origin（结果送回触发会话）。接受建议时可用任意 cron 表达式、"every 2h" 式间隔或 ISO 时间戳覆盖 schedule。

监控清单（watchlist）配置

清单是一个 JSON 文件，默认路径 ~/.hermes/literature-watch.json，可用 hermes config set skills.config.literature_watch.watchlist <路径> 改。结构：

{
  "topics": ["retrieval augmented generation"],
  "authors": ["A5023888391"],
  "dois": ["10.1038/nature12373"]
}

• topics：主题词，走 OpenAlex search= 检索；
• authors：OpenAlex author id（形如 A...，先用 literature-analysis 工作流 D 查到）；
• dois：论文 DOI，监控它们的新引用者（OpenAlex cites: 过滤）。

去重状态文件默认 ~/.hermes/literature-watch.seen.json，由脚本自动维护；换机器或重新统计时可删除，删除后下一轮把窗口内结果全部当作新增。

每次运行的流程

1. 读取 watchlist 与状态文件；窗口默认最近 7 天（--days 可调）。
2. 逐来源查询（全部是 scripts/watch.py 里标注 live 的函数，真实 HTTPS）：
   • 主题 → fetch_topic_works；作者 → fetch_author_works；DOI → fetch_citing_works。
3. filter_unseen 按 DOI → OpenAlex id → 归一化标题的优先级去重（本轮内部与历史状态双重去重）。
4. 只输出新增条目（年份、标题、DOI）；无新增明确说"无新增"。
5. 写回状态文件。

手动跑一次（等同 blueprint 每轮做的事）：

python ${HERMES_SKILL_DIR}/scripts/watch.py --run --watchlist ~/.hermes/literature-watch.json

数据源与限制

• OpenAlex 匿名查询有日预算（2026-09 核查为 $0.10/日，免费 key $1/日）与 100 req/s 上限；key 放 OPENALEX_API_KEY 环境变量，只发给 api.openalex.org。429 时有界退避，最多 3 次。
• from_publication_date 按出版日期过滤，数据库收录有延迟，边界日可能漏收或重复；去重机制吸收重复，漏收不补偿。
• Crossref 仅作 DOI 元数据兜底（fetch_crossref_record），无 key，遵守公共节流。
• 无 DOI 无 OpenAlex id 的条目靠标题去重，同名不同文会被误判为已见；报告里保留 id 便于复核。

Verification

离线自检不触网，验证去重与清单解析；live 查询明确 SKIP：

# smoke-test: true
import os, subprocess, sys
from pathlib import Path
base = Path(os.environ.get('SKILL_DIR', '.')).expanduser().resolve()
result = subprocess.run([sys.executable, str(base / 'scripts' / 'watch.py'), '--self-test'],
                        capture_output=True, text=True, timeout=60)
assert result.returncode == 0, result.stderr
assert 'SKIP live OpenAlex/Crossref checks' in result.stdout
print(result.stdout.strip().splitlines()[-1])