企业官网建设流程全解析

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

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

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）：

核心机制：技能即清单（零 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，逐条记录抓取状态，整批可审计。

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

蒸馏的"作业要求"只有一份：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 收尾

最后一步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，任何一步都可以重跑而不会破坏既有内容。