Zeng740307 Hot Monitor Docs

AI热点情报台 Skill 封装说明

目的：这份文档用于说明当前已落地的工作区原生 Skill 封装结果，并保留能力边界、触发语句、参数映射与工作流示例，供后续维护与扩展参考。

当前落地状态

当前项目已经落地 1 个工作区原生 Agent Skill：

• .github/skills/hot-monitor/SKILL.md

随包附带文件：

• .github/skills/hot-monitor/references/api-contract.md
• .github/skills/hot-monitor/evals/evals.json

当前封装策略：

• 使用 1 个总 Skill 覆盖“查热点 / 管监控 / 配系统 / 触发扫描”四类意图
• 优先通过本地 HTTP API 执行，不依赖前端 UI 点击
• 兼容 http://localhost:8000 与 http://localhost:8001 两个端口
• 删除监控项时要求二次确认

已完成的联测范围：

• 状态读取
• 热点查询
• 监控新增与删除
• 扫描触发
• 设置更新

测试邮件未纳入自动联测默认步骤，因为会产生真实外部副作用。

1. Skill 目标

AI热点情报台面向 AI 编程博主，核心目标是把“发现热点、追踪关键词、确认系统状态、触发扫描”这四类动作封装成可复用的 Agent Skill。

技能不应依赖前端点击完成业务，而应直接调用后端 HTTP API。

2. 推荐拆分方式

建议至少拆成 4 个能力块，也可以合并为 1 个总 skill 后在内部路由：

3. 触发语句建议

下面这些自然语言，应该能稳定触发 skill：

• 帮我看一下今天有哪些 AI 热点
• 找热度大于 7 的热点
• 看看哪些热点是监控词命中的
• 帮我添加一个关键词监控：GPT-5
• 帮我监控 OpenAI 的 X 账号
• 把某个关键词监控停掉
• 立刻刷新热点
• 看一下现在系统有没有在扫描
• 帮我把扫描间隔改成 6 小时
• 发一封测试邮件看看通知通不通

4. 输入输出约定

4.1 查询类输出

查询热点或命中记录时，建议 skill 输出统一字段：

• 标题
• 来源名称
• 来源类型
• 热度分数
• 发现时间
• 发布时间（如果有）
• AI 摘要
• 是否监控词命中
• 是否已推送
• 原始链接

如果是列表结果，默认返回 5 到 10 条，除非用户明确要求更多。

4.2 变更类输出

新增、更新、删除或触发扫描时，建议输出：

• 动作是否成功
• 目标对象是谁
• 实际生效的关键参数
• 若失败，返回后端 message 或 detail

5. 安全与确认策略

• 新增关键词、更新设置、触发扫描：可以直接执行，但执行后要回显结果
• 删除关键词：建议先确认目标条目，避免误删
• 修改系统设置：如果用户没有给出完整值，skill 应先追问，而不是猜测
• 当热点扫描已经在执行时，skill 不应重复触发，而应转为说明当前状态

6. 真实接口规格

6.1 查询热点

GET /api/v1/topics?limit=20&min_heat=5&sort=heat

支持参数：

返回字段重点：

{
  "id": 1,
  "title": "Anthropic Launches Claude Opus 4.7",
  "summary": "Anthropic 发布新模型并强调安全能力。",
  "raw_content": "...",
  "source_url": "https://...",
  "source_name": "Anthropic Blog",
  "source_type": "官方",
  "heat_score": 8,
  "tags": ["Claude", "AI Safety"],
  "is_notified": false,
  "keyword_id": null,
  "published_at": "2026-04-21T08:00:00Z",
  "relevance_score": null,
  "relevance_reason": null,
  "engagement": { "likes": 320 },
  "source_metrics": {},
  "discovered_at": "2026-04-21T09:12:52Z"
}

6.2 手动触发扫描

POST /api/v1/topics/scan

成功返回：

{ "message": "扫描任务已触发，正在后台执行", "triggered": true }

如果已有扫描在执行中：

{ "message": "已有扫描任务正在执行，请稍后查看结果", "triggered": false }

6.3 监控词管理

GET    /api/v1/keywords
POST   /api/v1/keywords
PATCH  /api/v1/keywords/{id}
DELETE /api/v1/keywords/{id}
GET    /api/v1/keywords/{id}/hits

新增关键词示例：

{ "keyword": "GPT-5", "type": "keyword", "enabled": true }

新增账号示例：

{
  "keyword": "OpenAI 官方",
  "type": "account",
  "platform": "twitter",
  "account_id": "openai",
  "enabled": true
}

关键词列表筛选参数：

6.4 系统设置

GET  /api/v1/settings
PUT  /api/v1/settings
POST /api/v1/settings/test-email
GET  /api/v1/settings/status

状态返回重点字段：

{
  "scheduler_running": true,
  "next_run": "2026-04-21T09:55:00Z",
  "total_topics": 67,
  "total_keywords": 5,
  "scan_running": false,
  "scan_started_at": "2026-04-21T08:55:40Z",
  "scan_finished_at": "2026-04-21T08:57:01Z",
  "last_scan_success_at": "2026-04-21T08:57:01Z",
  "last_scan_duration_seconds": 81.0,
  "last_scan_error": null
}

7. 推荐工作流模板

7.1 “刷新热点”

1. POST /api/v1/topics/scan
2. 如果 triggered=true，再调用 GET /api/v1/settings/status 轮询扫描状态
3. 当 scan_running=false 时，向用户回报扫描完成情况

7.2 “帮我监控某个关键词”

1. 检查用户给出的词或账号信息是否完整
2. 调用 POST /api/v1/keywords
3. 返回新增条目 ID、监控类型、启用状态

7.3 “今天有哪些值得写的热点”

1. 调用 GET /api/v1/topics
2. 默认带上适度筛选，如 sort=heat 或 time_range=24h
3. 输出结构化列表，而不是直接回传原始 JSON

8. Base URL 约定

• 默认：http://localhost:8000
• 备用：http://localhost:8001

如果 skill 运行时默认端口访问失败，应允许切换 base URL，而不是直接判定服务不可用。

9. 封装建议

• 如果你打算做一个总 skill，description 应明确覆盖“热点、监控词、扫描、设置、系统状态”这些触发词
• 如果你打算拆 skill，优先拆成“热点查询”和“监控管理”两大块，配置与扫描控制可作为附属能力
• 最终 SKILL.md 应尽量直接复用这份文档里的能力边界、参数表和工作流模板，减少二次整理