revenue-centric-design 开发者指南:X API 抓取、原则蒸馏与自动更新流水线完整解析

原创2026-10-22 12:18:431,988 阅读

revenue-centric-design 开发者指南:X API 抓取、原则蒸馏与自动更新流水线完整解析

revenue-centric-design 把 101 条 SaaS 产品设计与增长原则(转化落地页、Onboarding 激活、流失挽回、定价心理学等)打包成了一个 Agent Skill。它的背后,是一条用 Python 搭建的可复现流水线:通过 X API 抓取作者推文、用 LLM 做原则蒸馏、再由 refresh_meta.py 自动更新 README/SKILL 元数据。本文将带你逐文件拆解这条自动更新流水线的实现原理。

项目概览:一条流水线如何"养"大一个 Skill

revenue-centric-design 自动更新流水线抓取的 X 推文配图:Swartz 五级意识阶梯图

Skill 的入口是 SKILL.md:Agent 只读它、references/ 和 assets/。真正的"生产线"藏在 updater/,它不属于安装的 Skill,纯粹是维护者工具。整体更新循环是一条清晰的流水线:

discover_new.py → 人工筛选 → new_posts.txt → update.py → 蒸馏 + REVIEW → 粘贴进 references/ → refresh_meta.py → commit
   (可选:找新帖)                      (增量拉取+暂存)      (LLM 蒸馏,人工把关)      (合并入册)          (同步数字)

对应 5 个核心脚本(完整清单见 updater/README.md):

文件 职责 依赖
updater/skill_lib.py Snowflake 日期解码、已收录 ID、主题/覆盖率/计数助手 纯标准库
updater/fetch_posts.py X API v2 抓取器(原文 + 引用帖 + 媒体,识别 X Article) Bearer Token
updater/update.py 增量差集检测 + 拉取新帖 + 生成蒸馏暂存包 Bearer Token
updater/distill.py (可选)Claude API 自动起草原则条目 anthropic + API key
updater/refresh_meta.py 重算并回写 README/SKILL 的计数与覆盖日期 纯标准库
updater/prompts/distill.md 蒸馏规范,全流水线唯一的"真理源" —

核心机制:技能即清单(零 API 调用算覆盖率)

这条流水线最巧妙的设计写在 updater/skill_lib.py 的注释里:不存在独立的"已收录清单"。已覆盖的推文集合,是从 references/*.md 中每条原则末尾的 @richardrx · … Source 链接反向解析出来的(正则匹配作者 status 链接里的数字 ID);而每条推文的发布日期,则直接从 推文 ID 本身解码——Twitter Snowflake ID 的高位就是毫秒时间戳(纪元 1288834974657),右移 22 位再加纪元即得创建时间,见 updater/skill_lib.py 的 snowflake_date()。

带来两个直接好处:

  • 覆盖率与计数零 API 调用:coverage() 扫一遍本地 Markdown 就能算出最早/最晚日期与去重后帖子数,永远不会与实际内容漂移;
  • 增量更新天然安全:new_posts.txt 里留旧 URL 也没关系,update.py 会先算差集,已收录的直接跳过。

增量更新:update.py 的三步"拉取 + 暂存"

人工把值得收录的推文 URL(一行一个)写进 updater/new_posts.txt 后,运行 python update.py,updater/update.py 做三件事:

  1. 算差集:读取候选 URL,用 skill_lib.included_ids() 过滤掉已在 references/ 中的 ID,只拉真正的新帖;
  2. 抓取:复用 updater/fetch_posts.py 的 API 逻辑(媒体下载被重定向到 staging/media/);
  3. 暂存(stage):每条新帖生成三样东西——staging/posts/<id>.md(规范化文本)、staging/media/<id>__*.jpg(原图)、以及 staging/prompts/<id>.md(把蒸馏规范 updater/prompts/distill.md + 该帖文本 + 图片路径预先拼好的提示词文件)。

也就是说,update.py 结束时,LLM 蒸馏所需的一切已经打包就绪,下一步只剩"翻译 + 提炼"。

X API v2 抓取原理:批量、展开与限流处理

updater/fetch_posts.py 是唯一的网络出口,几个实现细节值得新手学习:

  • 批量接口:走 https://api.x.com/2/tweets?ids=…,最多 100 条 ID 一次请求(chunked(ids, 100)),91 条的完整重建只需一次调用;
  • 一次拿全:expansions 参数展开 attachments.media_keys、referenced_tweets.id(引用帖)与作者,tweet.fields 额外请求 note_tweet(长文)和 article(X Articles)字段,见 updater/fetch_posts.py;
  • 两轮抓取(Pass A/B):第一轮拉目标帖子;被引用(quote)的推文在第一轮里媒体经常不完整,脚本收集这些 ID 再发第二轮,按"主帖"身份重取,保证引用帖的媒体与作者信息完整解析,见 updater/fetch_posts.py;
  • 媒体取原图:照片直接拼接 name=orig 拿原始分辨率,视频则选 bit_rate 最高的 mp4 变体(best_media_url);
  • 文本择优:长文 note_tweet > X Article 正文 > 短推 text(full_text),并保留原始 JSON 到 data/raw/<id>.json 以便日后重放;
  • 健壮性:429 限流时读取 x-rate-limit-reset 响应头自动等待重试;401/403 直接给出"检查 Bearer Token"的明确报错;网络错误最多重试 5 次;
  • YAML frontmatter:每篇输出都带 source url、点赞/转发数、is_article、long_form 等字段,其中 themes 与 use_in_skill 两个开关是留给人工策展编辑的。

输出汇总在 data/index.json,逐条记录抓取状态,整批可审计。

原则蒸馏:把一条推文变成一条原则

蒸馏产出的 Swiss Knife Index 功能-复杂度-效用曲线配图

蒸馏的"作业要求"只有一份:updater/prompts/distill.md。它要求把推文忠实译成英文并压缩成一条 60–110 词的固定格式条目:

## <祈使句标题>
**Principle.**  <1–3 句核心启发式>
**Apply when.**  <触发场景>
**The move.**  <具体动作;必须保留命名机制(decoy effect、GBB、Swiss Knife Index…)>
**Evidence.**  <仅当原文引用研究/数据/案例>
**Visual.**  <信息型图片说明> — ../assets/<filename>
**Voice.**  <原文金句,翻译后保留作者口吻>
**Source.** @richardrx · YYYY-MM-DD

两条铁律:只留原则,不做全文翻译;保留有名字的机制——认知偏见的"命名"本身就是价值(诱饵效应、损失厌恶、峰值终末定律……)。

执行蒸馏有两条路(updater/README.md):

  • 辅助式(推荐):把 staging/prompts/<id>.md 交给 Claude Code 等 Agent,它能查看图片来判断哪些图"承载信息"、从而写出 **Visual.** 行;
  • 自动式:python distill.py(updater/distill.py)把每条暂存提示连同图片(base64 编码)发给 Claude,用 pydantic 结构化输出解析出 {theme_slug, entry_markdown},草稿写入 staging/drafts/<id>.md。

无论哪条路,人工必须逐条审阅——规范再严格,品味与准确性把关在人。审阅通过后,原则按"新帖在前"的顺序粘贴进对应的 references/ 主题文件,保留的图片从 staging/media/ 拷入 assets/。

定价卡视觉层级配图:首行与末行加粗、中间行灰化,演示串行位置效应在定价表中的应用

合并阶段还有两条原则性规则(updater/README.md):

  • 默认只增不改:已有条目与各自的 Source 帖、日期绑定,任何更新都不会重写历史;作者修订框架时(如 RCD 原则从 10 条早期稿变为 9 条正典),新条目入库、旧条目标注 "(earlier version) … superseded by …",这是人工决策,流水线永不自动改写策展文本;
  • 边界随内容携带:updater/prompts/distill.md 明确禁止产出涉赌/博彩/赌场类原则——这是作者授权复用时的硬性前提。

元数据同步与成本:refresh_meta.py 收尾

定位与 GTM 主题收录的 TAM/SAM/SOM 同心圆市场细分图

最后一步 python refresh_meta.py(updater/refresh_meta.py)让文档数字自动对齐内容:它从 references/*.md 重算原则总数、主题数、每主题表格计数与覆盖日期区间,再用正则替换补丁回写 README.md 和 SKILL.md(含 shields.io 徽章)。

用法上有三层:--check 先干跑预览(也是幂等性自检);不带参数则只应用"确定性修复";加 --updated YYYY-MM-DD 才动"Last updated"日期,避免无意义的日期跳动。

成本几乎可忽略:X API 按量计费 $0.005/条帖读取,同一资源在 24 小时 UTC 窗口内去重计费——一次典型更新(几条新帖 + 引用帖 + 时间线扫描)只花几分钱;而 refresh_meta.py 与差集检测完全离线。

另有两个收尾细节:posts.txt 是全量重建清单(配合 updater/fetch_posts.py 可干净重建 data/),新增 URL 记得手工追加——但"活"的真理源永远是 references/;密钥(updater/.env)、data/、staging/ 均被 gitignore,脚本与文档入库,保证流程可复现、可审计。

总结

  • 技能即清单:已收录集合从 references/ 的 Source 链接反推,日期从 Snowflake ID 解码,覆盖率统计零 API 调用、永不漂移;
  • 拉取可重放:fetch_posts.py 批量 + 两轮展开 + 原图下载,raw JSON 与 index 全量留档;
  • 蒸馏有规范、有人工闸口:一份 updater/prompts/distill.md 定义输出形状,人审阅后才入 references/;
  • 元数据自动对齐:refresh_meta.py 保证 README/SKILL 的数字永远由内容算出,而不是手填。

整条流水线只用 Python 标准库(唯一的可选依赖是 anthropic),循环是 discover → curate → update → distill → merge → refresh,任何一步都可以重跑而不会破坏既有内容。

登录后查看全文
revenue-centric-design