介绍
# Topic Monitor
**监控重要内容。在事件发生时收到通知。**
主题监控器通过持续监控您关心的主题，并仅在真正重要时智能地提醒您，将您的助手从被动响应转变为主动出击。
---
## ⚡ 快速开始（v1.2.0 新增！）
**只想监控一个主题？只需一条命令：**
```bash python3 scripts/quick.py "AI Model Releases" ```
就这样！这会创建一个具有合理默认值的主题： - **查询：** 根据主题名称自动生成 - **关键词：** 从主题名称中提取 - **频率：** 每日 - **重要性：** 中等 - **渠道：** Telegram
### 快速开始选项
```bash # Basic - just a topic name python3 scripts/quick.py "Bitcoin Price"
# With keywords python3 scripts/quick.py "Security CVEs" --keywords "CVE,vulnerability,critical"
# High priority, hourly checks python3 scripts/quick.py "Production Alerts" --frequency hourly --importance high
# Custom query python3 scripts/quick.py "Competitor News" --query "CompanyName product launch funding"
# Different channel python3 scripts/quick.py "Team Updates" --channel discord ```
### 快速开始与完整设置对比
| 功能 | 快速开始 | 完整设置 | |---------|-------------|------------| | 速度 | ⚡ 1 条命令 | 📝 向导 | | 默认值 | 智能预设 | 可自定义 | | 用例 | 单个主题 | 多个主题 | | 配置 | 最小化 | 全面控制 |
**在快速开始后，您随时可以进行自定义：** ```bash python3 scripts/manage_topics.py edit ai-model-releases --frequency hourly ```
---
## 核心功能
1. **主题配置** - 使用自定义参数定义主题 2. **定时监控** - 以可配置的间隔自动搜索 3. **AI 重要性评分** - 智能过滤：即时提醒 vs 摘要 vs 忽略 4. **上下文摘要** - 不仅仅是链接，而是带有上下文的有意义摘要 5. **每周摘要** - 将低优先级发现整理成可读报告 6. **记忆集成** - 引用您过去的对话和兴趣
---
## 完整设置（交互式向导）
用于配置多个主题或高级选项：
```bash python3 scripts/setup.py ```
向导将引导您完成以下步骤：
1. **主题** - 您想监控哪些主题？ 2. **搜索查询** - 如何搜索每个主题 3. **关键词** - 哪些术语表示相关 4. **频率** - 检查频率（每小时/每日/每周） 5. **重要性阈值** - 何时发送提醒（低/中/高） 6. **每周摘要** - 将非紧急发现整理成摘要
向导会根据您的偏好创建 `config.json`。您可以随时编辑它，或使用 `manage_topics.py` 来添加/删除主题。
**示例会话：** ``` 🔍 Topic Monitor - Setup Wizard
What topics do you want to monitor? > AI Model Releases > Security Vulnerabilities >
--- Topic 1/2: AI Model Releases --- Search query for 'AI Model Releases' [AI Model Releases news updates]: new AI model release announcement Keywords to watch for in 'AI Model Releases'? > GPT, Claude, Llama, release
--- Topic 2/2: Security Vulnerabilities --- Search query for 'Security Vulnerabilities' [Security Vulnerabilities news updates]: CVE critical vulnerability patch Keywords to watch for in 'Security Vulnerabilities'? > CVE, vulnerability, critical, patch
How often should I check for updates? 1. hourly 2. daily * 3. weekly
✅ Setup Complete! ```
## 快速开始
已经知道怎么做了？这是手动方法：
```bash # Initialize config from template cp config.example.json config.json
# Add a topic python3 scripts/manage_topics.py add "Product Updates" \ --keywords "release,update,patch" \ --frequency daily \ --importance medium
# Test monitoring (dry run) python3 scripts/monitor.py --dry-run
# Set up cron for automatic monitoring python3 scripts/setup_cron.py ```
## 主题配置
每个主题包含：
- **name** - 显示名称（例如 "AI Model Releases"） - **query** - 搜索查询（例如 "new AI model release announcement"） - **keywords** - 相关性过滤器（["GPT", "Claude", "Llama", "release"]） - **frequency** - `hourly`、`daily`、`weekly` - **importance_threshold** - `high`（立即提醒）、`medium`（重要时提醒）、`low`（仅摘要） - **channels** - 提醒发送位置（["telegram", "discord"]） - **context** - 关心的原因（用于 AI 上下文摘要）
### 示例 config.json
```json { "topics": [ { "id": "ai-models", "name": "AI Model Releases", "query": "new AI model release GPT Claude Llama", "keywords": ["GPT", "Claude", "Llama", "release", "announcement"], "frequency": "daily", "importance_threshold": "high", "channels": ["telegram"], "context": "Following AI developments for work", "alert_on": ["model_release", "major_update"] }, { "id": "tech-news", "name": "Tech Industry News", "query": "technology startup funding acquisition", "keywords": ["startup", "funding", "Series A", "acquisition"], "frequency": "daily", "importance_threshold": "medium", "channels": ["telegram"], "context": "Staying informed on tech trends", "alert_on": ["major_funding", "acquisition"] }, { "id": "security-alerts", "name": "Security Vulnerabilities", "query": "CVE critical vulnerability security patch", "keywords": ["CVE", "vulnerability", "security", "patch", "critical"], "frequency": "hourly", "importance_threshold": "high", "channels": ["telegram", "email"], "context": "DevOps security monitoring", "alert_on": ["critical_cve", "zero_day"] } ], "settings": { "digest_day": "sunday", "digest_time": "18:00", "max_alerts_per_day": 5, "deduplication_window_hours": 72, "learning_enabled": true } } ```
## 脚本
### manage_topics.py
管理研究主题：
```bash # Add topic python3 scripts/manage_topics.py add "Topic Name" \ --query "search query" \ --keywords "word1,word2" \ --frequency daily \ --importance medium \ --channels telegram
# List topics python3 scripts/manage_topics.py list
# Edit topic python3 scripts/manage_topics.py edit eth-price --frequency hourly
# Remove topic python3 scripts/manage_topics.py remove eth-price
# Test topic (preview results without saving) python3 scripts/manage_topics.py test eth-price ```
### monitor.py
主监控脚本（通过 cron 运行）：
```bash # Normal run (alerts + saves state) python3 scripts/monitor.py
# Dry run (no alerts, shows what would happen) python3 scripts/monitor.py --dry-run
# Force check specific topic python3 scripts/monitor.py --topic eth-price
# Verbose logging python3 scripts/monitor.py --verbose ```
**工作原理：** 1. 读取待检查的主题（基于频率） 2. 使用 web-search-plus 或内置的 web_search 进行搜索 3. 使用 AI 重要性评分器对每个结果进行评分 4. 高重要性 → 立即提醒 5. 中重要性 → 保存供摘要使用 6. 低重要性 → 忽略 7. 更新状态以防止重复提醒
### digest.py
生成每周摘要：
```bash # Generate digest for current week python3 scripts/digest.py
# Generate and send python3 scripts/digest.py --send
# Preview without sending python3 scripts/digest.py --preview ```
输出格式： ```markdown # Weekly Research Digest - [Date Range]
## 🔥 Highlights
- **AI Models**: Claude 4.5 released with improved reasoning - **Security**: Critical CVE patched in popular framework
## 📊 By Topic
### AI Model Releases - [3 findings this week]
### Security Vulnerabilities - [1 finding this week]
## 💡 Recommendations
Based on your interests, you might want to monitor: - "Kubernetes security" (mentioned 3x this week) ```
### setup_cron.py
配置自动监控：
```bash # Interactive setup python3 scripts/setup_cron.py
# Auto-setup with defaults python3 scripts/setup_cron.py --auto
# Remove cron jobs python3 scripts/setup_cron.py --remove ```
创建 cron 条目： ```cron # Topic Monitor - Hourly topics 0 * * * * cd /path/to/skills/topic-monitor && python3 scripts/monitor.py --frequency hourly
# Topic Monitor - Daily topics 0 9 * * * cd /path/to/skills/topic-monitor && python3 scripts/monitor.py --frequency daily
# Topic Monitor - Weekly digest 0 18 * * 0 cd /path/to/skills/topic-monitor && python3 scripts/digest.py --send ```
## AI 重要性评分
评分器使用多种信号来决定提醒优先级：
### 评分信号
**高优先级（立即提醒）：** - 重大突发新闻（通过时效性 + 关键词密度检测） - 价格变动 >10%（针对金融主题） - 完全匹配您关键词的产品发布 - 您正在使用的工具中的安全漏洞 - 对您提出的具体问题的直接回答
**中优先级（值得放入摘要）：** - 相关新闻但不紧急 - 跟踪产品的次要更新 - 您主题中的有趣进展 - 教程/指南发布 - 高参与度的社区讨论
**低优先级（忽略）：** - 重复新闻（已提醒过） - 略微相关的内容 - 低质量来源 - 过时信息 - 垃圾邮件/促销内容
### 学习模式
启用后（`learning_enabled: true`），系统会： 1. 跟踪您与哪些提醒进行了交互 2. 根据您的行为调整评分权重 3. 建议主题优化 4. 自动调整重要性阈值
学习数据存储在 `.learning_data.json` 中（保护隐私，绝不共享）。
## 记忆集成
主题监控器连接到您的对话历史记录：
**示例提醒：** > 🔔 **Dirac Live 更新** > > 3.8 版本发布，包含您上周询问的房间校正改进。 > > **上下文：** 您提到过在工作室中低频响应的问题。此次更新包含新的低频优化。 > > [链接] | [详细信息]
**工作原理：** 1. 读取 references/memory_hints.md（创建此文件） 2. 扫描最近的对话日志（如果可用） 3. 将发现与过去的上下文匹配 4. 生成个性化摘要
### memory_hints.md（可选）
帮助 AI 建立关联：
```markdown # Memory Hints for Topic Monitor
## AI Models - Using Claude for coding assistance - Interested in reasoning improvements - Comparing models for different use cases
## Security - Running production Kubernetes clusters - Need to patch critical CVEs quickly - Interested in zero-day disclosures
## Tech News - Following startup ecosystem - Interested in developer tools space - Tracking potential acquisition targets ```
## 提醒渠道
### Telegram
需要 OpenClaw 消息工具：
```json { "channels": ["telegram"], "telegram_config": { "chat_id": "@your_username", "silent": false, "effects": { "high_importance": "🔥", "medium_importance": "📌" } } } ```
### Discord
由 Agent 传递（技能配置中无 Webhook）：
`monitor.py` 发出 `DISCORD_ALERT` JSON 载荷，OpenClaw 通过消息工具发送它们。这与 Telegram 提醒流程匹配（结构化输出，技能代码中无直接 HTTP）。
```json { "channels": ["discord"] } ```
SMTP 或 API：
```json { "channels": ["email"], "email_config": { "to": "[email protected]", "from": "[email protected]", "smtp_server": "smtp.gmail.com", "smtp_port": 587 } } ```
## 高级功能
### 提醒条件
微调提醒时机：
```json { "alert_on": [ "price_change_10pct", "keyword_exact_match", "source_tier_1", "high_engagement" ], "ignore_sources": [ "spam-site.com", "clickbait-news.io" ], "boost_sources": [ "github.com", "arxiv.org", "official-site.com" ] } ```
### 正则表达式模式
匹配特定模式：
```json { "patterns": [ "version \\d+\\.\\d+\\.\\d+", "\\$\\d{1,3}(,\\d{3})*", "CVE-\\d{4}-\\d+" ] } ```
### 频率限制
防止提醒疲劳：
```json { "settings": { "max_alerts_per_day": 5, "max_alerts_per_topic_per_day": 2, "quiet_hours": { "start": "22:00", "end": "08:00" } } } ```
## 环境变量
配置这些环境变量以自定义 topic-monitor：
| 变量 | 默认值 | 描述 | |----------|---------|-------------| | `TOPIC_MONITOR_TELEGRAM_ID` | — | 用于接收提醒的您的 Telegram 聊天 ID | | `TOPIC_MONITOR_DATA_DIR` | 技能目录中的 `.data/` | 存储状态和发现的位置 | | `WEB_SEARCH_PLUS_PATH` | 相对于技能 | web-search-plus search.py 的路径 | | `SERPER_API_KEY` / `TAVILY_API_KEY` / `EXA_API_KEY` / `YOU_API_KEY` / `SEARXNG_INSTANCE_URL` / `WSP_CACHE_DIR` | — | 通过子进程环境变量允许列表传递的可选搜索提供商变量 |
**示例设置：** ```bash # Add to ~/.bashrc or .env export TOPIC_MONITOR_TELEGRAM_ID="123456789" export TOPIC_MONITOR_DATA_DIR="/home/user/topic-monitor-data" export WEB_SEARCH_PLUS_PATH="/path/to/skills/web-search-plus/scripts/search.py" ```
## 状态管理
### .research_state.json
存储在 `TOPIC_MONITOR_DATA_DIR` 中（默认：技能目录中的 `.data/`）。
跟踪： - 每个主题的最后检查时间 - 已提醒的 URL（去重） - 重要性评分历史 - 学习数据（如果启用）
示例： ```json { "topics": { "eth-price": { "last_check": "2026-01-28T22:00:00Z", "last_alert": "2026-01-28T15:30:00Z", "alerted_urls": [ "https://example.com/eth-news-1" ], "findings_count": 3, "alerts_today": 1 } }, "deduplication": { "url_hash_map": { "abc123": "2026-01-28T15:30:00Z" } } } ```
### .findings/ 目录
存储值得放入摘要的发现：
``` .findings/ ├── 2026-01-22_eth-price.json ├── 2026-01-24_fm26-patches.json └── 2026-01-27_ai-breakthroughs.json ```
## 最佳实践
1. **保守起步** - 最初设置 `importance_threshold: medium`，根据提醒质量进行调整 2. **使用上下文字段** - 帮助 AI 生成更好的摘要 3. **优化关键词** - 添加否定关键词以过滤噪音：`"keywords": ["AI", "-clickbait", "-spam"]` 4. **启用学习** - 根据您的行为随时间改进 5. **每周审查摘要** - 不要忽略摘要——它能揭示模式 6. **结合 personal-analytics** - 根据您的聊天模式获取主题建议
## 与其他技能的集成
### web-search-plus
自动使用智能路由： - 产品/价格主题 → Serper - 研究主题 → Tavily - 公司/初创公司发现 → Exa
### personal-analytics
根据对话模式建议主题： > "您本月询问了 Rust 12 次。想让我监控 'Rust language updates' 吗？"
## 隐私与安全
- **所有数据本地化** - 除搜索 API 外不使用外部服务 - **状态文件已 gitignore** - 可以安全地在版本控制的工作区中使用 - **记忆提示可选** - 您控制共享哪些上下文 - **学习数据保留在本地** - 绝不会发送到 API - **子进程环境变量允许列表** - monitor 仅转发 PATH/HOME/LANG/TERM 和搜索提供商密钥 - **技能代码中无直接 HTTP** - 提醒作为 JSON 发出，由 OpenClaw 传递
## 故障排除
**没有发送提醒：** - 检查 cron 是否正在运行：`crontab -l` - 验证渠道配置（Telegram 聊天 ID、Discord/email 的主题渠道列表） - 使用 `--dry-run --verbose` 运行以查看评分
**提醒太多：** - 提高 `importance_threshold` - 添加频率限制 - 优化关键词（添加否定过滤器） - 启用学习模式
**漏掉重要新闻：** - 降低 `importance_threshold` - 增加检查频率 - 扩大关键词范围 - 检查 `.research_state.json` 是否存在去重问题
**摘要未生成：** - 验证 `.findings/` 目录是否存在并有内容 - 检查摘要 cron 计划 - 手动运行：`python3 scripts/digest.py --preview`
## 示例工作流
### 跟踪产品发布
```bash python3 scripts/manage_topics.py add "iPhone 17 Release" \ --query "iPhone 17 announcement release date" \ --keywords "iPhone 17,Apple event,September" \ --frequency daily \ --importance high \ --channels telegram \ --context "Planning to upgrade from iPhone 13" ```
### 监控竞争对手
```bash python3 scripts/manage_topics.py add "Competitor Analysis" \ --query "CompetitorCo product launch funding" \ --keywords "CompetitorCo,product,launch,Series,funding" \ --frequency weekly \ --importance medium \ --channels discord,email ```
### 研究主题
```bash python3 scripts/manage_topics.py add "Quantum Computing Papers" \ --query "quantum computing arxiv" \ --keywords "quantum,qubit,arxiv" \ --frequency weekly \ --importance low \ --channels email ```
## 致谢
为 ClawHub 构建。使用 web-search-plus 技能进行智能搜索路由。