last30days-skill：用 Agent 驱动多源搜索，按真实互动为过去 30 天打分的技术拆解

本文基于 last30days-skill 仓库的 README.md 及其引擎源码编写，覆盖该项目的核心定位（用 Reddit、X、YouTube、HN、Polymarket 等真实用户互动数据打分，而非编辑聚合）、全部安装路径、BYO-Keys 配置矩阵、~/.config/last30days/.env 配置项、七步研究流水线，以及 v3 引擎在 skills/last30days/scripts/lib/pipeline.py 等文件中的并发抓取、RRF 融合与聚类的实现证据。读完你可以独立完成安装、按源配置凭据、使用 --discover / --plan / --store 等参数运行研究，并理解结果排名的底层原理。

一、定位：搜索"人"而不是"编辑"

README 给出的核心论点是：Google 聚合的是编辑内容，而 /last30days 搜索的是真实人群。Reddit 的 upvote、X 的点赞、YouTube 的观看与完整字幕、TikTok 的互动、Polymarket 用真金白银背书的赔率——每天有大量人在用注意力和钱包投票，每个平台却是各自的"围墙花园"（独立的 API、token、认证）。没有任何单一 AI 能同时访问全部，而 last30days 的思路是：用户自带 keys 和浏览器会话，由 Agent 把十几个断开的平台桥接起来，并行检索、交叉打分，再由 Agent 裁判综合成一份 brief。

作者的使用场景在 README.md 中写得很具体：销售前 30 分钟了解一家公司的真实近况、会前读完对方的近期推文与播客字幕、出差前了解哪些游乐项目关闭、动手写代码前知道社区实际在踩什么坑。典型命令只有一行：

/last30days Peter Steinberger

README 强调合成结果按"真实人群的参与度"排序——社交相关性（social relevancy），而非 SEO 相关性。一条 1,500 upvotes 的 Reddit 帖，是比一篇无人阅读的博文更强的信号。

二、安装：六种 Surface 与更新方式

Surface	安装	更新
Claude Code（推荐）	/plugin marketplace add mvanhorn/last30days-skill	市场自动更新，或 claude plugin update last30days@last30days-skill
Grok（xAI Build CLI）	grok plugin marketplace add mvanhorn/last30days-skill 后 grok plugin install last30days	grok plugin update last30days
Codex、Cursor、Copilot、Gemini CLI 等 50+ Agent Skills 宿主	npx skills add mvanhorn/last30days-skill -g	npx skills update last30days -g
claude.ai（Web）	从最新 release 下载 last30days.skill，在 Customize > Skills > Create skill 中上传	重新下载并上传
Claude Desktop	下载对应平台的 .mcpb 拖入 Settings > Extensions	重新下载并拖入新包
OpenClaw	clawhub install last30days-official	clawhub update last30days-official

几个要点来自 README.md：

• Claude Code 推荐原因：marketplace 会替你处理更新，插件缓存按版本管理，新 release 发布时自动刷新。注意 Claude Code 不跨安装方式去重：marketplace 插件和 npx skills 拷贝同时激活时，/last30days 会出现两个条目，每台机器用一种安装方式即可。
• -g 全局标志：npx skills add mvanhorn/last30days-skill -g 安装到用户目录，跨项目可用；不加 -g 则装到项目内 ./.skills/。可以用 -a codex、-a cursor、-a gemini-cli 指定一个或多个 harness。
• Claude Desktop 前置条件：.mcpb 包内是 MCP server，需要系统上有 Python 3.12+（包内带引擎源码，但使用你本地的 Python 解释器）。粘贴哪些源的 API key 均可选——全部跳过时引擎降级为仅 Web 模式；key 存入系统钥匙串。README 明确说明 Desktop 与 Claude Code 的凭据存储相互独立，不共享。
• 手动（开发者）：git clone 后把 skills/last30days 软链到 ~/.claude/skills/last30days，软链保证与工作树同步，无需重新拷贝。

运行时 skill 规格以 skills/last30days/SKILL.md 为权威（当前版本 3.23.0，与 pyproject.toml 中的 version = "3.23.0" 一致），README 跟踪 v3 流水线；两者不一致时以 SKILL.md 为准。

三、数据源全景：哪些免费、哪些要 key

README 的源清单按"人群告诉你什么"组织，这里是完整继承：

Source	人群信号
Reddit	未经过滤的观点。带真实 upvote 数的热门评论，免费、无需 API key
X / Twitter	热点观点、专家长帖、突发反应。最快知道、最快争论
YouTube	45 分钟深度长视频，全量字幕里检索真正重要的 5 句可引用内容
TikTok	触达 360 万人的创作者观点，Google 上永远搜不到
Instagram Reels	带口播字幕的网红视角，视觉文化信号
Hacker News	开发者共识，技术人群真正争论的地方
Polymarket	不是观点而是赔率，真金白银背书
GitHub	人物：PR 速度、按 star 排序的头部仓库、release notes；主题：issues 与 discussions
Digg	Digg AI 1000 榜单的策展故事簇（约 1000 个高信号 AI 账号），digg-pp-cli 在 PATH 上自动启用，无需 X 认证
arXiv	炒作背后的论文，免费无 key，arxiv-pp-cli 在 PATH 上自动启用
Techmeme	技术新闻编辑层，按你的 30 天窗口取数，免费无 key
LinkedIn	职业信号，文章被加权为高信号
StockTwits	交易者情绪，主题为股票代码或加密货币时自动激活
Threads	后 Twitter 文本层，创作者与品牌的对话
Pinterest	视觉发现，产品与创意的 pin、收藏、评论
Xiaohongshu (RED)	中文生活方式/产品/创作者信号，需本地运行登录态 x-mcp 插件或 xiaohongshu-mcp，按次 --search xhs 显式启用
Bluesky	去中心化社交层，AT Protocol 帖子
Perplexity	受控 Agent API 合成、OpenRouter Sonar 回退、原始 Search API 行、显式 Deep Research
Web	编辑类报道与博客对比，只是众多信号之一

Trust Social 等小众源也已进入引擎。README 还记录了 v3.3 到 v3.11.1 期间的 175 个合并 PR（其中 122 个来自 52 位社区贡献者）、社区安全加固（HTML 渲染器 XSS 修复、CI 供应链加固、测试覆盖率从 60% 提升到 84% 的下限等），MIT 协议、无追踪、研究数据留在本机。

BYO-Keys 矩阵（README 原文继承）：

Sources	需要什么	成本
Reddit（含评论）+ HN + Polymarket + GitHub + StockTwits	什么都不需要	免费
arXiv + Techmeme	免费 CLI，首次运行自动安装	免费
X / Twitter	任意浏览器登录 x.com，或设置 XQUIK_API_KEY / XAI_API_KEY	浏览器 cookie 免费；key 按供应商计费
YouTube	brew install yt-dlp	免费
Bluesky	bsky.app 的 App Password	免费
TikTok + Instagram + Threads + Pinterest + LinkedIn + YouTube 评论	ScrapeCreators key	10,000 次免费调用，之后按量付费
Xiaohongshu (RED)	运行登录态 x-mcp 浏览器插件或 xiaohongshu-mcp 服务，--search xhs 或 INCLUDE_SOURCES=xiaohongshu 启用；引擎自动探测 http://localhost:18060 再 http://host.docker.internal:18060，或 XIAOHONGSHU_API_BASE 指定自定义地址	无 last30days 侧 key
DripStack（付费财经简报）	显式 opt-in：--search dripstack 或 INCLUDE_SOURCES=dripstack	无 key，免费公开搜索 API
Perplexity Agent API / Search API / Deep Research	Perplexity key，或 OpenRouter key 作为 Sonar 回退	按量付费；直连 key 解锁 Agent API 与后台 Deep Research
Web search	Brave Search key	每月 2,000 次免费查询

macOS Keychain（可选）：key 可以存进系统钥匙串而不是 .env 文件，作为最低优先级来源自动读取——.env 与进程环境变量冲突时仍然优先：

# 交互式设置，逐个提示已知 key，空输入跳过
skills/last30days/scripts/setup-keychain.sh

# 或手工存单个 key
security add-generic-password -a "$USER" -s last30days-XAI_API_KEY -w "xai-..."

# 查看 / 清理
skills/last30days/scripts/setup-keychain.sh --list
skills/last30days/scripts/setup-keychain.sh --delete XAI_API_KEY

条目以 last30days-<KEY> 服务名存储；非 Darwin 平台加载器是 no-op。若已有其他服务名下的 key，可用 LAST30DAYS_KEYCHAIN_ALIASES 映射复用，见 CONFIGURATION.md 的 "Reusing existing macOS Keychain items" 一节。

四、Day-1 配置：存储路径、结构化输出与长期监测

README 的 Configuration 一节列出六个"第一天就会用到"的能力，完整继承如下：

1. 研究文件保存位置。 LAST30DAYS_MEMORY_DIR 默认 ~/Documents/Last30Days/（Windows 为 C:\Users\<you>\Documents\Last30Days\）。可用环境变量覆盖，或 --save-dir <path> 按次指定；--output <file> 指定渲染结果的精确路径（格式由 --emit 决定）；--save-suffix=<name> 让同一主题的不同变体分开保存（例如按客户）。每次 --save-dir 运行产出 <slug>-raw[-suffix].md。运行 python3 skills/last30days/scripts/last30days.py --preflight 可以在研究前审查计划写入。源码层面，skills/last30days/scripts/last30days.py 的 _main 中可见三层解析链：--save-dir 显式参数 → 进程环境变量 → .env 配置，且刻意用 is None 判断而非 truthy or，避免空字符串被静默吞掉。

2. 面向 Agent 的结构化输出。 直接向引擎运行 python3 skills/last30days/scripts/last30days.py "AI coding agents" --emit=json 得到稳定的版本化 agent profile；只有需要未版本化的内部 Report 原始 dump 时才加 --json-profile=raw。字段参考与版本策略见 docs/reference/json-export.md：agent 导出当前 schema_version 为 1.2，顶层恒含 schema_version、query、generated_at、window_days、source_status、freshness_verdicts、clusters、results；discovery 导出是独立的版本化契约（schema_version 1.1，kind: "discovery"，outcome 可为 "nothing-solid"）。

3. 无主题发现（topic-less discovery）。 问 /last30days what's trending in AI agents? 得到按速度排序的发现 brief，而不是研究已知主题；agent 宿主上会执行"三命令宿主裁判协议"（模型负责命名主题、过滤垃圾、打分、撰写内容角度）。脚本/cron 直连引擎：python3 skills/last30days/scripts/last30days.py --discover "AI agents"（one-shot：确定性主题名、无角度），加 --emit=json 得到版本化 discovery 契约。--discover 与位置参数主题、--drill 互斥。

4. 跨运行趋势监测。 默认模式每次运行生成一份全新的 markdown 快照。要跨时间累积，加 --store 持久化到 SQLite，然后用 skills/last30days/scripts/watchlist.py 做定时运行（新发现可选 Slack / webhook 推送），用 skills/last30days/scripts/briefing.py 做日/周摘要。完整节奏模式见 CONFIGURATION.md 的 "Trend monitoring" 一节。

5. 可订阅的研究库。 运行 python3 skills/last30days/scripts/last30days.py library feed 把已保存的 brief 转成 index.html、本地 Atom feed.xml 和可读的 brief 页面。--publish 只在你想托管 HTML 索引时加——发布是显式 opt-in 且默认公开；要让 Atom feed 可订阅，把输出目录托管到 GitHub Pages 等静态主机即可。

6. 检索已研究过的内容。 python3 skills/last30days/scripts/last30days.py library search "MCP servers" 离线且确定性地增量索引同一批已保存 brief，合并匹配的运行内 store 记录，按主题和日期分组。新的运行若与当前主题重叠，会显示紧凑的 From your library 区块；LAST30DAYS_LIBRARY_CONTEXT=off 可关闭这个被动上下文。

CLI 的完整参数面在 skills/last30days/scripts/last30days.py 的 build_parser() 中定义，包括：--emit（compact/json/context/md/html/brief）、--quick / --deep、--days 与 --as-of（历史回看）、--x-handle / --x-related / --github-user / --github-repo / --subreddits / --dedicated-subreddits / --tiktok-hashtags / --tiktok-creators / --ig-creators、--plan（宿主模型自产 JSON 查询计划，跳过引擎内部规划器）、--competitors [N]（自动发现 N 个竞品并扇出对比，1..6）、--hiring-signals（把招聘页作为证据解读公司方向）、--store、--max-results / --max-per-source / --max-source-fetches（覆盖深度档位的配额）、--corpus <dir>（把本地 md/txt/pdf 目录作为私有排序源，可重复）、--publish-html / --publish 等。--discover 家族则对应三命令协议：--nominate-only（Leg 1 提名）、--judgments <file>（Leg 2 按宿主判断恢复研究）、--finalize [--angles <file>]（Leg 3 渲染终稿并记录主题队列）。

五、How it works：七步流水线

README 的流程描述是：

1. 你输入主题。 人物、公司、产品、技术、"X vs Y"，什么都行。
2. Agent 解析"谁重要"。 找到 X handle（含创始人）、GitHub 仓库、subreddit、TikTok 话题标签、YouTube 频道。对 "Kanye West" 知道 r/hiphopheads、@kanyewest 和 YouTube 上的 "bully review"；对 "OpenClaw" 解析 GitHub 上的 openclaw/openclaw 并抓取实时 star 数。
3. 所有源并行检索。 多查询扩展，按参与度、相关性、新鲜度打分。
4. 别人没有的深度。 反应视频的完整 YouTube 字幕、带 upvote 数的 Reddit 顶部评论、TikTok 文案、Polymarket 赔率——不只有标题和链接。
5. 同一故事合并。 Reddit 上宣布、X 上讨论、TikTok 上票价 = 一个 cluster，而不是三条分离的结果。
6. 合成为一份 brief。 基于具体数据，按源引用，按真实互动排序。不是"我找到了这些"，而是"这些才重要"。
7. 然后它成为你的专家。 跑完一次后，Claude 会话知道社区知道的一切。可以继续追问、写提示词、起草邮件、规划行程、设计系统——全部扎根于"当下真实"。

六、Reddit 与 X 检索的实现原理

docs/how-search-works.md 给出了两条主搜索链路的架构（v3 早期版本描述，方向与当前源码一致）：

User: /last30days "kanye west"
          ↓
    ┌─────┴─────┐
    ↓           ↓           (concurrent via ThreadPoolExecutor)
 [REDDIT]    [X/TWITTER]
    ↓           ↓
 OpenAI     Bundled Bird or
 API        xAI API
    ↓           ↓
 Parse       Parse
    ↓           ↓
 Enrich      ───┘
 (fetch         ↓
  actual     [MERGE]
  upvotes)      ↓
    ↓        [NORMALIZE → FILTER → SCORE → DEDUPE]
    └───────────↓
          [OUTPUT to SKILL.md agent]

两条链用 ThreadPoolExecutor 并发执行。Reddit 侧：搜索之后对每条线程做"enrichment"——打 Reddit 免费 JSON API（https://reddit.com/r/{sub}/comments/{id}/{slug}/.json，无需 key）拿真实 score、评论数、upvote ratio、Top 10 评论（文本+分数）和 created_utc 真实日期。"这就是为什么 Reddit 结果带真实互动指标而不是 AI 估算"。README 提到 Reddit 公开 .json API 死亡后，免费路径靠 keyless RSS + shreddit 抓取（#457）、arctic-shift 专用 subreddit 发现（#696）和"相关性下限"（#488，防止病毒式偏题帖劫持 brief）重建。对应源码文件：skills/last30days/scripts/lib/reddit_public.py、skills/last30days/scripts/lib/reddit_enrich.py、skills/last30days/scripts/lib/reddit_listing.py、skills/last30days/scripts/lib/reddit_arctic.py、skills/last30days/scripts/lib/reddit_rss.py。

X 侧有两类后端，自动探测：捆绑的 Bird 客户端（env 认证 AUTH_TOKEN/CT0，免费、无弹框）优先，XAI_API_KEY（付费，grok-4-1-fast 模型 + x_search 工具）回退，两者皆无则整体跳过 X。两者都返回真实 X API 互动数据；差别在相关性分——Bird 默认 0.7 由 skills/last30days/scripts/lib/relevance.py 重排，xAI 返回 AI 评估的 0.0–1.0。README 记录 X 管线在 #610–#622 一轮做过推倒重建：FROM 与 ABOUT 双车道（本人的帖与被讨论的对话分别排序）、人物感知子查询消歧、第一方作者身份 grounding 与互动信号排序、单 X 源带后端自动 failover，外加如实探测认证状态的 --diagnose。对应模块：skills/last30days/scripts/lib/bird_x.py、skills/last30days/scripts/lib/xai_x.py、skills/last30days/scripts/lib/xurl_x.py、skills/last30days/scripts/lib/xquik.py、skills/last30days/scripts/lib/grok_x.py。

后处理（两源通用）：归一化 → 日期硬过滤 → 参与度加权的相关性打分 → 排序 → 按 URL 去重 → 若全部被过滤则兜底保留相关性 Top 3。错误处理分层：HTTP 3 次重试指数退避（1s→2s→3s）、模型访问错误自动切链路上下一模型、Reddit enrichment 按条目 try/catch（失败保留未富化项）、X 后端静默降级 Bird → xAI → 跳过、整体错误存为 reddit_error/x_error 展示给用户。对应 skills/last30days/scripts/lib/http.py 与 skills/last30days/scripts/lib/dedupe.py。

七、v3 引擎源码视角：并发、融合与配额

深入 skills/last30days/scripts/lib/pipeline.py（约 5,000 行，v3 编排核心），可以确认 README 描述的每个机制都有对应实现：

• 源清单即 import 面：文件头部的 from . import (...) 一次性列出全部源模块——amazon、arxiv、bird_x、bluesky、brightdata、corpus、digg、dripstack、github、grok_x、hackernews、instagram、linkedin、perplexity、pinterest、polymarket、reddit 家族、stocktwits、techmeme、telegram、threads、tiktok、truthsocial、trustpilot、x 家族、xiaohongshu_api、youtube_yt 等，与 README 源表一一对应。

• 并行抓取：with ThreadPoolExecutor(max_workers=max(1, len(plan.sources))) 让每个 (源, 子查询) 流并发执行；重试阶段另开 min(4, ...) 个 worker。

• 融合与聚类：各流候选先过 weighted_rrf（带权 RRF 融合），再 cluster_candidates 聚成簇——README 第 5 步"同一故事合并"的实现落点。去重由 skills/last30days/scripts/lib/fusion.py 的 collapse_duplicate_urls 完成。

• 深度档位的实际配额（DEPTH_SETTINGS）：

  深度	per_stream_limit（每流上限）	pool_limit（融合池上限）	rerank_limit
  quick	6	15	12
  default	12	40	40
  deep	20	60	60

  这正是 --max-results / --max-per-source / --max-source-fetches 三个覆盖参数作用的默认值（argparse 帮助文本引用 issue #716）。

• 每源抓取上限：MAX_SOURCE_FETCHES = {"x": 2, "jobs": 1, "linkedin": 1, "stocktwits": 1, "trustpilot": 1, "amazon": 1, "telegram": 1}——trustpilot 和 amazon 每个子查询都用同一个公司/产品标识符，多流是纯冗余，故封顶为 1；X 默认只让前两个子查询真正抓取。

• 失败严重度排序：_FAILURE_SPECIFICITY 把 auth-failed < rate-limited < schema-drift < timeout < unreachable < error 排序，用于源结果的降级表达；SKILL.md 的 "per-run source outcomes" 规则（no-results 是干净的零命中，其余状态不得写成"X 上没讨论"）就是基于这套 taxonomy。

• CLI 子命令分发：main() 用 parse_known_args 把 setup 家族（--device-auth/--github/--openclaw）透传；doctor、library feed、library search、queue list、queue cover 走话题词精确匹配分发（含 doctor 的 --cached/--postmortem/--probe 修饰），所以这些子命令不会和"研究一个恰好叫 doctor 的话题"冲突——精确匹配才路由，多词话题照常研究。

八、诊断、健康检查与确定性保障

README 与 SKILL.md 都强调"不要猜为什么 X 返回很薄"：

• python3 skills/last30days/scripts/last30days.py --diagnose：打印 provider 与源可用性 JSON，其中 available_sources 是凭据解析后的权威源集合——SKILL.md 明确要求不要靠检查 .env 推断源可用性，因为 key 可能来自进程环境、Keychain、pass(1) 等。
• python3 skills/last30days/scripts/last30days.py doctor：渲染四态审计——WORKING、TURNED ON - UNVERIFIED、NOT WORKING、COULD BE ON——每源一行，外加 CLI 健康块与缩进的备份/评论子车道。--postmortem 读上次运行的 last-report.json 报告实际坏在哪；--probe 做有界在线探测（只探免费 HTTP + keyless CLI 源，计费源绝不探测）；--cached --json 服务 TTL（LAST30DAYS_DOCTOR_TTL，默认 900 秒）内的缓存报告。实现见 skills/last30days/scripts/lib/doctor.py 与 skills/last30days/scripts/lib/prescriptions.py。
• --preflight：安全的权限预检——展示配置来源、浏览器 cookie 计划、计划写入、可选命令与被忽略的项目配置，不读 cookie、不写文件、不跑研究。非模态宿主（Codex desktop 等文件夹模式）首次研究前被要求先跑它。实现见 skills/last30days/scripts/lib/permission_preflight.py。
• 确定性评估：仓库内置研究质量评估套件——skills/last30days/scripts/evaluate_search_quality.py 与 tests/eval/（breaking-event、comparison、emerging-event、niche、non-english-cjk、person、tech-product 七组 fixture 各含 http.json 与 manifest.json，加 tests/eval/baseline.json 与 tests/eval/harness.py）；--record-fixtures <dir> 是隐藏的开发专用 flag，录制脱敏后的 HTTP 响应到 <dir>/http.json，规则见 docs/reference/eval.md。测试规模上，pyproject.toml 配置 pytest + pytest-cov，tests/ 目录含 200+ 测试文件（README 称 2,700+ tests），CI 设有测试覆盖率下限。
• 配置信任边界：项目内隐藏配置 .claude/last30days.env 默认被忽略，除非从进程环境或全局配置设置 LAST30DAYS_TRUST_PROJECT_CONFIG=1（防仓库投毒）；--corpus 本地语料是隐私例外——配置了语料时引擎绕过托管后端本地执行，且语料证据默认排除在 --publish-html、library feed --publish 与 agent JSON 之外（LAST30DAYS_CORPUS_IN_EXPORT=1 才是显式导出 opt-in）。相关契约测试见 tests/test_project_config_trust.py、tests/test_security_boundaries.py。

九、关键文件索引

文件	作用
README.md	项目 README，安装/源/配置/流程总览
skills/last30days/SKILL.md	运行时 skill 规格（权威），含输出契约、三命令发现协议、预检清单
CONFIGURATION.md	逐源 key 矩阵、推理 provider 优先级、Web 后端优先级、doctor 与趋势监测细节
skills/last30days/scripts/last30days.py	主 CLI 入口，argparse 参数面与子命令分发
skills/last30days/scripts/lib/pipeline.py	多源并发编排、RRF 融合、聚类、doctor/diagnose
docs/how-search-works.md	Reddit/X 双链路架构图与错误处理表
docs/reference/json-export.md	agent JSON 导出的字段参考与版本策略
docs/reference/eval.md	确定性研究质量评估套件的 fixture 规则
CONTRIBUTING.md / CHANGELOG.md / CONTRIBUTORS.md	贡献流程、版本史、社区贡献者

适用前提与限制：引擎要求 Python 3.12+（SKILL.md 的 Runtime Preflight 会按 python3.14→3.13→3.12→python3→python 顺序探测，找不到且宿主有 uv 时自动经 uv 安装一个约 28MB 的受管 CPython 3.12）；X 源依赖浏览器 cookie、XAI_API_KEY、XQUIK_API_KEY 或 Grok CLI 之一，缺失时该源被跳过而非失败；TikTok/Instagram 等付费源默认关闭，需 ScrapeCreators key 与 INCLUDE_SOURCES 显式打开。版本能力以本仓库实际内容（v3.23.0）为准。