last30days-skill 项目总结

[!info]
本文基于 mvanhorn/last30days-skill 当前主分支源码整理。分析时对应提交为 1221584，最近提交信息为 chore(release): v3.3.2 (#485)，提交时间为 2026-06-06。

项目介绍/说明

last30days-skill 是一个面向 Agent Runtime 的开源研究型 Skill。它的目标不是做传统网页搜索，而是让 AI Agent 在最近 30 天内跨多个社区、社交平台、视频平台、预测市场和代码平台检索真实讨论，再把这些证据整理成一份可读 briefing。

项目的核心定位可以概括为：用 Agent 去搜索“最近真实人群在讨论什么”，并按互动信号、时效性、相关性和来源质量进行排序，而不是只依赖搜索引擎的 SEO 结果或模型训练数据。

它同时具备两层产品形态：

• Agent Skill 层：skills/last30days/SKILL.md 定义运行契约、输出格式、预检流程、引用规则、比较模式和宿主模型应该如何生成 query plan。
• Python Engine 层：skills/last30days/scripts/last30days.py 是 CLI 入口，实际负责配置读取、数据源探测、多源检索、归一化、重排、聚类、渲染和保存。

项目支持 Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLI、OpenClaw 等多种宿主环境。官方推荐的通用安装方式是 Agent Skills CLI：

npx skills add mvanhorn/last30days-skill -g

Claude Code 也可以通过 marketplace 安装：

/plugin marketplace add mvanhorn/last30days-skill
/plugin install last30days

项目解决的痛点

1. 大模型知识滞后

普通 LLM 回答依赖训练数据或有限联网能力，面对 AI 工具、开源项目、热点人物、社区反馈、产品口碑这类快速变化的信息时，很容易落后。last30days-skill 把问题限定在最近一段时间，并主动抓取社区讨论、视频 transcript、GitHub 活动和预测市场数据，解决“模型知道的不是现在发生的事”的问题。

2. 传统搜索过度依赖网页和 SEO

Google 或普通 web search 更容易返回官网、博客、新闻稿、媒体文章。很多真实意见存在 Reddit 评论、X 帖子、Hacker News 讨论、YouTube 长视频、TikTok 内容、GitHub Issue/PR 里。这个项目把这些平台作为一等数据源，强调“社交相关性”而不是单纯的网页相关性。

3. 多平台信息孤岛

X、Reddit、YouTube、TikTok、GitHub、Polymarket 等平台的数据格式、认证方式、搜索能力、互动指标都不一致。手动跨平台查资料非常耗时，也难以统一排序。项目通过多个 source adapter 把不同平台统一成 SourceItem，再进入同一套归一化、打分、融合和聚类流程。

4. 手工研究成本高

典型使用场景包括会前调研、竞品分析、工具选型、产品需求洞察、热点事件复盘、提示词学习。原本需要人工打开多个平台逐条看帖子、评论、视频和 issue；现在可以由 Agent 并发检索，再输出一份结构化 briefing。

5. “热度”和“可信度”难以同时处理

项目并不把互动量等同于事实，但它把点赞、转发、评论、upvote、浏览量、预测市场概率、GitHub star/PR 活动等作为信号之一，再结合 relevance、freshness、source quality 做融合排序。这样能把“社区确实在关注什么”显式纳入研究结果。

项目剖析

总体架构

项目结构的核心文件如下：

重点原理

1. Skill Contract 驱动 Agent 行为

这个项目的一个关键设计点是：它不是只有代码，而是把 SKILL.md 当作产品入口。SKILL.md 明确规定宿主模型必须做什么，例如：

• 对命名实体类 topic，宿主模型应先做 pre-research，尽量解析 X handle、GitHub 用户、相关 subreddit 等。
• 宿主模型需要生成 JSON query plan，并通过 --plan 传给 Python 引擎。
• Python 引擎输出的 badge、证据块、footer、HTML briefing 等有固定格式。
• 用户可见的最终结果需要避免裸 URL、避免末尾堆来源列表，并用 inline markdown link 引用证据。

这相当于把“提示词工程”提升为一份可版本化、可测试、可分发的 Agent 协议。

2. Query Plan 先行

planner.py 会把用户 topic 转成一个结构化的 QueryPlan：

topic -> intent -> freshness_mode -> cluster_mode -> subqueries -> source_weights

每个 SubQuery 包含：

• label：子查询标签。
• search_query：适合平台检索的关键词查询。
• ranking_query：适合语义重排的自然语言问题。
• sources：要搜索的数据源。
• weight：该子查询在融合排序中的权重。

如果宿主模型传入 --plan，引擎会优先使用外部计划；否则会尝试调用内部 reasoning provider；再不行则走 deterministic fallback。项目文档里多次强调，命名实体场景应该由宿主 Agent 先生成 plan，否则结果会变薄。

3. 多源并发检索

pipeline.py 会根据配置和可用依赖判断数据源是否启用。默认可用的数据源包括 Reddit、Hacker News、Polymarket；如果本地有 gh 或 token，可启用 GitHub；如果有 yt-dlp 可启用 YouTube；如果有 X cookie、xAI key 或 ScrapeCreators key，可启用 X/Twitter 等。

核心检索使用 ThreadPoolExecutor 并发执行。每个 source 会被包装为统一的 retrieval stream，返回原始 item 和可能的 artifact。项目还做了这些工程处理：

• 对部分 source 设置 fetch cap，避免重复请求。
• 发现 429 后共享 rate-limit 状态，减少无效调用。
• 对 5xx transient error 做一次重试。
• GitHub 有 person-mode 和 project-mode，优先按用户或仓库做定向检索。
• Reddit 支持 public JSON enrichment，拉取真实 upvote、评论数、top comments。

4. 统一数据模型

不同平台返回的数据会被归一化成 SourceItem。关键字段包括：

• source：来源，如 reddit、x、youtube、github。
• title、body、url、author、container。
• published_at、date_confidence。
• engagement：平台互动指标。
• relevance_hint、why_relevant、snippet。
• metadata：平台特有补充信息。

统一模型的好处是：后续 relevance、freshness、dedupe、snippet、fusion、cluster 都不用关心原始平台差异。

5. 归一化、去重、融合、重排

单个 source 的处理流程大致是：

raw items
  -> normalize_source_items
  -> signals.annotate_stream
  -> prune_low_relevance
  -> dedupe_items
  -> extract_best_snippet

跨 source 的排序则大致是：

items_by_source_and_query
  -> weighted_rrf
  -> rerank_candidates
  -> score_fun
  -> enrich GitHub stars
  -> cluster_candidates
  -> render

其中 weighted_rrf 是加权 reciprocal rank fusion，用来把多个子查询、多种来源的候选项合并成统一候选池；rerank_candidates 再调用 reasoning provider 或 fallback 进行语义重排；score_fun 会给“有传播性/有趣的观点”额外打分，服务于 Best Takes 这类输出。

6. 聚类而不是简单列表

项目不是直接输出 N 条结果，而是把同一故事、同一讨论点、同一产品反馈合并成 Cluster。例如同一事件可能同时出现在 Reddit、X 和 YouTube，聚类后会成为一个主题块，而不是重复出现三次。

这对研究 briefing 很重要：用户关心的是“发生了什么、为什么重要”，不是原始链接列表。

项目主要流程

flowchart TD
    A[用户输入 topic] --> B[宿主 Agent 解析意图]
    B --> C[预检与实体解析]
    C --> D[生成或读取 QueryPlan]
    D --> E[last30days.py 解析参数与配置]
    E --> F[pipeline 判断可用数据源]
    F --> G[并发检索 Reddit / X / YouTube / HN / GitHub / Polymarket 等]
    G --> H[归一化 SourceItem]
    H --> I[相关性 / 新鲜度 / 互动指标打分]
    I --> J[去重与 snippet 提取]
    J --> K[加权 RRF 融合]
    K --> L[LLM 或 fallback 重排]
    L --> M[跨来源聚类]
    M --> N[compact / md / json / html 渲染]
    N --> O[保存 raw 结果或 HTML briefing]
    O --> P[宿主 Agent 综合为最终回答]

数据源与能力

项目使用

基础安装

Claude Code 推荐方式：

/plugin marketplace add mvanhorn/last30days-skill
/plugin install last30days

Codex、Cursor、Gemini CLI、Copilot 等 Agent Skills 宿主：

npx skills add mvanhorn/last30days-skill -g

更新：

npx skills update last30days -g

常见命令

普通研究：

/last30days OpenClaw

比较研究：

/last30days "OpenAI vs Anthropic vs xAI"

导出 HTML briefing：

/last30days OpenClaw --emit=html

命令行直接运行：

python3 skills/last30days/scripts/last30days.py "OpenClaw" --emit=compact

指定保存目录：

python3 skills/last30days/scripts/last30days.py "OpenClaw" --save-dir ~/Documents/Last30Days

启用 SQLite 存储，适合后续 watchlist 和 briefing：

python3 skills/last30days/scripts/last30days.py "AI coding agents" --store

诊断当前可用数据源：

python3 skills/last30days/scripts/last30days.py --diagnose

常用参数

配置文件

项目支持多层配置，优先级大致是：

1. 进程环境变量。
2. 当前项目的 .claude/last30days.env。
3. 全局 ~/.config/last30days/.env。
4. macOS Keychain 中 last30days-<KEY> 命名的凭据。

常见配置示例：

LAST30DAYS_MEMORY_DIR=~/Documents/Last30Days
BRAVE_API_KEY=<your-brave-key>
SCRAPECREATORS_API_KEY=<your-scrapecreators-key>
INCLUDE_SOURCES=tiktok,instagram,threads
XAI_API_KEY=<your-xai-key>
BSKY_HANDLE=<your-handle>.bsky.social
BSKY_APP_PASSWORD=<your-app-password>

风险与限制

1. 数据源可用性不稳定

很多平台没有稳定、低成本、官方友好的搜索接口。X、TikTok、Instagram、YouTube 等都可能遇到登录、cookie、API 限流、反爬、费用和地区网络问题。因此同一个 topic 在不同机器、不同 key 配置下，结果质量可能明显不同。

2. 互动量不是事实

项目把 upvote、like、view、comment、prediction odds 等作为信号，但互动量只能说明“有人关注或参与”，不能直接证明内容真实。高 stakes 场景仍然需要回到原始来源核验。

3. Query Plan 质量决定上限

命名实体、竞品比较、人物研究如果没有解析出正确的 handle、repo、subreddit、hashtag，很容易搜偏。项目把这部分放在宿主 Agent 的 pre-research 和 --plan 里，设计上是合理的，但也意味着宿主模型的规划能力会直接影响最终结果。

4. Skill Contract 很长，维护成本高

SKILL.md 本身很长，里面有大量历史失败模式和强约束规则。优点是能把 Agent 行为收敛到稳定模板；缺点是维护成本高，且不同宿主模型可能仍然遗漏部分协议。因此项目用版本、测试、渲染器 badge、footer 等机制来加强契约。

5. 凭据与隐私需要谨慎

项目默认把研究结果保存到本地目录，也支持 .env 和 macOS Keychain。使用时要注意 .env 权限、API key 管理、cookie 来源，以及 raw 结果里是否包含不适合外发的内容。

可借鉴点

1. “Skill = 协议 + 引擎”

这个项目最值得借鉴的不是某个爬虫适配器，而是产品形态：把 Agent 的行为协议、运行入口、工程代码、配置文档、测试和输出契约打包成一个 Skill。这样比单纯写一个 CLI 更适合 Agent 生态分发。

2. 宿主模型负责 planning，代码负责 execution

项目把“理解 topic、解析实体、生成 query plan”交给宿主模型，把“并发检索、归一化、去重、排序、保存”交给 Python 引擎。这种分工很适合 Agent 工具：模型做模糊理解，代码做确定性执行。

3. 多源证据需要统一 schema

SourceItem -> Candidate -> Cluster -> Report 的数据模型让后续算法可以不关心平台差异。以后扩展新数据源，只要把原始结果转成统一 schema，就能接入相同 pipeline。

4. briefing 比链接列表更有价值

项目的输出目标不是“找到链接”，而是“帮用户理解最近发生了什么”。所以它强调聚类、跨源合并、Best Takes、HTML briefing、raw 保存、watchlist 和 weekly briefing。这种设计更贴近真实研究工作流。

项目总结

last30days-skill 是一个很典型的 Agent 时代工具：它不是替代搜索引擎，也不是单纯的爬虫，而是把多个封闭平台的近期讨论整合成 Agent 可消费的研究上下文。

它解决的问题可以总结为三句话：

1. 让 AI Agent 获取比训练数据更新的社区信息。
2. 把 Reddit、X、YouTube、GitHub、Polymarket 等孤岛数据统一到一个研究 pipeline。
3. 把原始搜索结果转成带证据、带排序、可复用的 briefing。

从工程上看，它的价值在于把 prompt contract、CLI engine、source adapters、schema、pipeline、render、store、watchlist 组合成一个完整产品，而不是只做一个脚本。对我们做 Agent 控制台、企业研究工具、竞品情报、内容调研、产品反馈聚合时，都有较强参考意义。

推荐使用场景：

• 会前人物或公司调研。
• AI 工具、开源项目、技术方案的最近 30 天口碑分析。
• 竞品比较和市场热度观察。
• 产品需求洞察，尤其是从 Reddit、HN、GitHub issue 中找用户痛点。
• 内容创作前的社区观点和素材收集。

不推荐把它当成唯一事实来源。它更适合作为“近期讨论雷达”和“研究上下文生成器”，最终结论仍应结合官方文档、原始帖子、代码仓库和权威来源核验。

参考链接

• mvanhorn/last30days-skill
• README.md
• skills/last30days/SKILL.md
• CONFIGURATION.md
• docs/how-search-works.md
• CHANGELOG.md