Communitygithub.com

sansheng-distill -- 书籍/视频蒸馏引擎 (v2 浏览型)

输入一本书的电子全文或一组视频,运行完整管道,生成一个可直接 file:// 打开的交互式 HTML 蒸馏页面。

视频蒸馏引擎 (v2 浏览型) 是什麼?

這是一個專為 Claude Code 設計的知識蒸餾引擎技能,能夠將書籍全文或影片系列轉換為結構化的「瀏覽型」HTML 蒸餾頁面。它支援從電子書格式(如 epub, pdf, mobi)或 YouTube 等影片平台作為輸入,並自動進行診斷、內容壓縮、詳實轉述、網路增補、跨書索引等一系列步驟。最終產出一個單檔案(≤3MB)的互動頁面,包含「一眼全書」「全書詳實」「書魂」「行動與自檢」「該信幾分·延伸」五個分頁,以及腦圖、書魂視覺化、頁內子視圖等豐富互動功能。此技能特別強調內容的真實性和可追溯性:所有關鍵論點、金句、案例都必須錨定原文,並在頁面上顯示來源。它也內建了嚴格的品質門禁(G1-G15)和出廠驗證(Step7),確保每一份蒸餾成品都達到標準,且絕不允許編造數據或繞過驗證。

相容平台✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add sandypoli-boop/sansheng-skills

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

sansheng-distill -- 書籍/影片蒸餾引擎(v2 瀏覽型)

請輸入一本書的電子全文(或一組影片),執行 Step0-Step7 管線(Step2 分兩遍),產出一個可使用 file:// 直接開啟的單檔案互動 HTML 蒸餾頁面。

v2 頁型 = 瀏覽型「凝練地圖 + 詳實正文 + 頁內二級視圖」,繼承舊版驗證過的五段漏斗:

Tab裝什麼
① 一眼全書真封面 hero + 餐巾紙公式 + 核心觀點獨立模組 + 可點跳腦圖 + 精選金句(給 3 分鐘掃讀的人)
② 全書詳實逐章 800-1500 字詳實轉述,論點式標題,預設全展開不折疊(給願讀 30 分鐘的人)
③ 書魂全書最核心那條反直覺主張的可視化(並排對照 / 流程鏈 / 曲線)
④ 行動與自檢因果鏈 + 心智模型 + 決策規則 + 第二人稱自檢問句(純瀏覽,無評分)
⑤ 該信幾分·延伸批判層四分區 + 內在張力 + 書評 + 跨書互鏈 + 三張頁內子視圖入口(作者/同類書/觀點對比)

互動:腦圖可點跳章節、章節詳實層預設全展開、書魂可視化、3 個頁內全螢幕子視圖(hash 路由開合)、多主題換膚。

這是入口編排檔案。 先讀本文對齊管線,再在每一步按下表讀對應 reference / 執行對應 script;references 是各步的執行細則,不要憑記憶做。

路徑與變數約定(全文只定義一次)

佔位符展開為
$SKILL本 skill 目錄(安裝後為 ~/.claude/skills/sansheng-distill)
$DATA書資料根目錄,由環境變數 DISTILL_DATA_DIR 指定(預設 ./distill-data)
{slug}書的 ASCII kebab 短名(如 jinqian-xinlixue);全站唯一,別撞投資 NN/育兒 pNN
{書目錄}本書資料目錄,純 {slug}(如 jinqian-xinlixue);不含書名,避免中文目錄名、git/Windows 友好

命令裡的佔位符替成實值再執行。單書目錄首次執行 Step0 時自動建立。

資料目錄約定(單書產物佈局)

$DATA\
  knowledge-index.json          # 跨書概念索引(全庫共享,Step4 維護,自動 .bak)
  {書目錄}\
    book.txt                    # 全文(書=Step0-B;影片=Step0-V 組裝的轉寫語料)  -- gitignore
    diagnose.json               # 入書診斷(書=Step0-B;影片=Step0-V 的 video_series 變體)
    raw\                        # 僅影片:各集原始轉寫 srt/txt(Step0-V)             -- gitignore
    series-input.json           # 僅影片:手寫 manifest(Step0-V 輸入)
    series.json                 # 僅影片:規範化 manifest(Step0-V 產物,下游只讀它)
    comments.json               # 僅影片:觀眾評論(Step0-V,供 Step3 enrich.reviews)
    distill.json                # 蒸餾主物件 v2(Step2 兩遍產:Pass1 骨架 + Pass2 narrative/excerpts)
    _pass2_g*.json              # Pass2 分塊中間態(長書按章 fan-out 各組產物,合併回 distill) -- gitignore
    enrich.json                 # 聯網增補 v2(Step3:author_page/similar_page/views_page + reviews + cross_book_external,附來源 URL,可整塊降級)
    index-merge.json            # 5-tag 合併清單(Step4 中間產物)
    {slug}.html                 # 單檔案互動蒸餾頁(Step6 產物,最終交付,≤3MB;真封面 base64 內聯,無獨立 cover 檔案)
    _verify.png                 # Step7 驗證全頁截圖                                  -- gitignore

gitignore(建議在資料目錄加 .gitignore):book.txt / raw/ / _verify.png / _pass2_*.json / *.bak 不入庫(版權原文 / 臨時產物);其餘(distill / enrich / HTML / index-merge / series / comments / diagnose)可入庫。


管線表(Step0-Step7,Step2 分兩遍)

每一步:做什麼 / 讀哪個 reference / 執行哪條命令 / 產物 / 失敗降級。逐步照做,上一步產物是下一步輸入。

步做什麼讀哪個 reference執行哪條命令產物失敗降級
Step0-B 入書診斷 + 轉 txt(蒸書走此行)電子書 → 全文 txt + 診斷(格式/可提取/掃描版/亂碼率/目錄識別)腳本自足;分流規則見 method.md §0python $SKILL\scripts\convert_book.py "<書檔案>" --outdir "$DATA\{書目錄}"(重轉加 --force)book.txt / diagnose.jsonexit 2 = 缺依賴/格式不支援/拒覆蓋 → 裝 calibre(azw3·mobi)或補 pip 依賴或加 --force;exit 3 = 需OCR / 需人工確認 → 停下問使用者(見硬門禁①),不硬讀、不編內容
Step0-V 影片系列入庫(蒸影片走此行)每個影片取材轉寫 → 手寫 manifest → 組裝語料 + 抓評論。章節=集數method.md §V.0(取材 cascade,固定流程,先讀) + §V。分流:YouTube 優先抓字幕(認準人工字幕,video-to-subtitle-summary)/ 無字幕或需畫面語義 → Gemini 原生線上(claude-gemini-video,免下載)/ 非 YouTube 先下載再解析① 按 §V.0 取每影片乾淨轉寫(YouTube 人工字幕 subtitle.{lang}.vtt 可直接餵 build_series;⚠️ 別用滾動重複 3× 的 text.txt/自動字幕),存 $DATA\{書目錄}\raw\{NN}_{id}\;② 手寫 series-input.json(transcript 指向選定的乾淨字幕檔案);③ python $SKILL\scripts\build_series.py --manifest "<series-input.json>" --outdir "$DATA\{書目錄}";④ python $SKILL\scripts\fetch_comments.py --series "$DATA\{書目錄}\series.json" --out "$DATA\{書目錄}\comments.json";⑤ 逐條 yt-dlp --skip-download --print 抓熱度中繼資料(播放/讚/評論數/日期,供熱度條;--flat-playlist 拿不到須逐條 full extract)book.txt / series.json / diagnose.json / comments.jsonbuild exit 3 = 全部影片缺轉寫/亂碼 → 停下問使用者(見硬門禁①);fetch exit 2 = 全失敗或抖音不支援 → 評論整塊降級(enrich.reviews 置 null),不阻塞蒸餾
Step1 書型判定讀診斷 + 全書抽樣(首/中/末章),判 論說/敘事/人物/工具 型,定加權欄位與硬門檻method.md §1無(讀 diagnose.json + book.txt 抽樣)book_type(寫入 distill.json)邊界模糊按 §1.2 順序裁決,命中即停;傳記重思維 → 人物(不判敘事)
Step2·Pass1 壓縮骨架(凝練地圖)三輪認知壓縮 + 四嫁接件(決策規則/心智模型/內在張力/批判段)+ v2 延展欄位(生活類比/主次/金句點評/概念誤讀/書魂/因果鏈/自檢)+ 逐條補錨點與證據等級method.md §2-§5(§3 三輪 + §4 四嫁接件 + §4.5 延展欄位 + §5 錨點)無(內化方法蒸餾,產出 JSON)distill.json 骨架層(除 chapters[].narrative/.excerpts 外全部欄位)diagnose=分組蒸餾 → 走 method.md §8 分組再合成(禁一次性硬吞);產出後過 §7 門禁 G1-G15 自查(見硬門禁②)
Step2·Pass2 詳實轉述(詳實正文)逐章兩級檢索(先讀 Pass1 骨架保結構,再回 book.txt 該章原文 grep 案例/數字/原話保血肉)→ 講書稿式 narrative(坡道開場 → 觀點+完整案例故事+資料 → 一句接主線)+ 挑 excerpts。長書按章 fan-out 並行(每組≤5 章派 1 subagent 全 Opus,組內串行,主控合併)method.md §3.5(兩級檢索 / 講書稿模板 / 版權線 / fan-out)無(內化;長書分組各產 _pass2_g*.json 中間態,主控回填 distill.json)回填 distill.json 的 chapters[].narrative(書 800-1500 字/章·影片段落 ≥400)+ chapters[].excerpts(書每章 ≥1,原文 ≤150 字)grep 不到支援就降級不寫該點,禁憑印象編案例/編數字;主控做 G9 字數 / G14 excerpts 機械核對 + 標誌性案例保全抽檢(招牌故事必須整段完整出現,不得壓成標籤)
Step3 聯網增補(三頁內子視圖 + 內聯)三張二級頁各起一輪專門搜尋:作者頁 / 同類書頁 / 觀點對比頁(國內外贊同方/質疑方);另產內聯 reviews(書評正反)+ cross_book_external(跨書外部立場),全帶來源 URL。影片系列:reviews/views_page 資料來源含 Step0-V 的 comments.json,author_page 改頻道頁,詳見 enrich.md §Venrich.md(§3 三塊搜尋 pass;§4 豆瓣反爬;影片看 §V)聯網檢索(AnySearch → Tavily → WebSearch,工具鏈見 enrich.md §3.4);影片 reviews/views 讀 comments.jsonenrich.json(五頂層鍵:author_page/similar_page/views_page/reviews/cross_book_external)某塊全檔抓不到 → 該鍵置 null 整塊隱藏(子視圖 + 入口一併刪);蒸餾主體不依賴網路,聯網失敗不阻塞
Step4 跨書索引登記 + 互鏈distill.concepts 逐個與現有索引語義匹配,賦 5-tag(SUPPORTS/REFINES/CONTRADICTS/NEW_SUB_ASPECT/NEW_CONCEPT),登記本書 entry + 渲染 ⑤ M11 已蒸書互鏈cross-book.md(§2 精確四步 + §3 tag 判定)① python $SKILL\scripts\update_index.py query --index "$DATA\knowledge-index.json" --names-only → ② 寫 index-merge.json → ③ ... register --index "$DATA\knowledge-index.json" --merge "$DATA\{書目錄}\index-merge.json" --dry-run(exit 0)→ ④ 去 --dry-run 真跑index-merge.json / 更新 knowledge-index.json(+.bak) / M11 互鏈資料register exit 1 = 校驗錯 → 按 stderr 逐條修 index-merge.json 回 ③ 重校驗(禁用 --force 繞 exit 1);exit 2 = 同書 slug 衝突 → 確為重蒸才加 --force,slug 撞車則換唯一 slug
Step5 設計兩遍工作法為這本書出 token plan + signature 決策,過對抗自審;品牌鎖八成、書魂放兩成design-craft.md(兩遍工作法)+ brand-tokens.md(主題 token 契約)無(設計決策,內化到 Step6 填槽)token/signature 定調(不落獨立檔案,直接指導 Step6)signature 命中反 slop 黑名單(藍紫漸變/emoji 圖示/圓角+左邊框卡濫用/湊數資料)→ 改;襯線模式必配 CJK 襯線兜底
Step6 生成單檔案 HTML複製骨架填**五 tab + 17 區塊 + 3 頁內子視圖(SUB01-03)**的槽,刪乾淨 dummy,可降級區塊(M10/M11/子視圖)整塊刪html-spec.md(§1 五 tab + 區塊規格表 / §3 生成流程 / §4 腦圖 md / §5 體積 / §6 extract 相容)複製 $SKILL\templates\page-skeleton.html 到 $DATA\{書目錄}\{slug}.html 後逐槽填充(vendor 已內聯,勿動)$DATA\{書目錄}\{slug}.html(單檔案,≤3MB)超體積預算按 html-spec.md §5 先刪 dummy 再壓 excerpts 再壓封面(WebP data URI/降尺寸);禁刪 vendor/必需區塊/data-source,禁壓 narrative 跌破 G9
Step7 出廠驗證 v2靜態 lint + 契約門禁 + Playwright 冒煙:體積≤3MB / 必需區塊齊 / 五 tab 文案+panel id 對 / panel-full 章節均非 details 且 narrative 字數達標(書≥800·影片≥400)/ 章標題論點式(黑名單+長度)/ 書籍真封面 img[src^="data:image"] / 3 子視圖與入口·返回一致 / 無「顯示出處」開關且 .src-note 常顯 / 無獨立金句牆 / 零外鏈 / lang="zh" / data-source≥20 / token 塊外零 hex / 主題切換 body 背景變化html-spec.md §3(違規修復優先級)python $SKILL\scripts\verify_page.py "$DATA\{書目錄}\{slug}.html" --distill "$DATA\{書目錄}\distill.json" --screenshot "$DATA\{書目錄}\_verify.png"; echo "退出碼=$?"退出碼 + _verify.png 全頁截圖exit 1 = 有違規,按輸出逐條修後重跑;exit 0 才算 Step7 / 本書完成(見硬門禁③)。絕不放寬 verify 或刪檢查項來「過關」

⚠ 影片路徑 v2 尚未執行 E2E 驗證:骨架 / method.md §V / html-spec.md §V / enrich.md §V / verify_page.py 的影片分支已隨 v2 更新到位,但尚未使用影片樣本完整重蒸驗收(書樣本《金錢心理學》已 E2E 通過)。蒸影片系列時按 §V 照做,遇到骨架/門禁與影片不吻合的坑先記錄再修。 執行判成敗的腳本別用 \| tail / \| head 取摘要(管道退出碼取最後一段,tail 永遠成功會吞失敗);看完整結尾行或補 ; echo "退出碼=$?"。

StepA · 作者演變聚合(可選,同一作者 ≥2 部已蒸時)

某作者在 $DATA 下已蒸 ≥2 部作品時,可選做「思想演變專題」聚合頁;單書蒸餾不涉及,<2 部不生成。

  • 做什麼:只讀各書 distill.json(絕不重蒸)聚合為 author.json → 渲染作者演變頁 author.html(4 視圖:時間線 / 母題 ribbon / 思想轉向 / 概念演化圖)。每書蒸餾頁頂部「演變入口卡」(SLOT:AUTHOR-ENTRY)鏈到它。
  • 讀哪個 reference:author-craft.md(§0 事實 vs 敘事鐵律 / §2 author.json schema / §4 四視圖資料契約 / §5 區塊骨架 / §6 轉向證偽層 / §7 入口卡)。
  • 執行哪條命令:python $SKILL\scripts\build_author.py --author "<作者名>" --data-root "$DATA" --manual "$DATA\authors\{author_slug}\author.manual.json" --enrich "$DATA\authors\{author_slug}\author.enrich.json" --out "$DATA\authors\{author_slug}\author.json"(已有 author.json 且 manual 缺失時防覆蓋欄拒跑,確需重建加 --force;<2 部 exit 3 不生成);再複製 templates\author-page-skeleton.html、把 #author-data 槽替換為該 author.json 生成 author.html。
  • 產物:$DATA\authors\{author_slug}\author.json + author.html。
  • 觸發門檻 / 降級:該作者 <2 部已蒸 → build_author.py exit 3 不生成、連網搜(enrich)不啟、每書頁入口卡整卡刪。
  • 出廠驗證:python $SKILL\scripts\verify_page.py "$DATA\authors\{author_slug}\author.html"; echo "退出碼=$?"(自動識別作者頁走獨立門禁:4 視圖齊 / 零外鏈 / Zero-Hex / lang=zh / 破折號 / 深鏈格式 / 轉向 verdict 一致;exit 0 才算完成)。

硬門禁(三處,不過不許往下走)

  1. Step0 exit 3 → 停下問使用者:診斷判「需OCR」(掃描版純圖)或「需人工確認」(gb18030 疑似假字/亂碼率>2%)時,不啟動蒸餾、不硬讀、不編內容,把 diagnose 結論報給使用者定奪(補 OCR / 換檔案 / 人工核編碼)。影片系列同理:build_series.py exit 3(全部影片都缺轉寫,一個都沒抓到)→ 停下問使用者(補轉寫 / 換影片 / 核 manifest),不拿空語料硬蒸。
  2. Step2 兩遍品質門禁自查(G1-G15):Pass1 骨架 + Pass2 詳實轉述產出後,按 method.md §7 逐條自查(通用 G1-G7 + 書型專項 + v2 詳實/瀏覽層 G8-G15)。空洞誇讚 / 無錨點論斷 / 硬門檻未達 / 公式含糊 / 敘事壓成標籤 / 章標題非論點式(G8)/ narrative 詳實度不足(書<800·影片<400 字·G9)/ layman_analogy 有空(G10)/ soul_module 不合規(G11)/ self_check·action_chain 越界(G12/G13)/ excerpts 缺或超 150 字版權紅線(G14)/ primary·featured 越界(G15) = 打回重蒸 / 回補,不帶病進 Step6。
  3. Step7 verify v2 exit 0 才算完成:verify_page.py(v2,傳 --distill 追加契約門禁)退出碼非 0 就不是成品。按輸出修資料/樣式後重跑,直到 exit 0。絕不放寬驗證閾值或刪檢查項來假過關。

鐵律(每步都守)

  • 錨點:蒸餾內容必須錨定原文,method.md §5.1 六類欄位(core_ideas / decision_rules / quotes / mental_models.evidence / chapters.excerpts / self_check)每條帶 anchor,上站進 data-source;無錨點論斷 = 門禁打回。
  • 論點式標題(v2):chapters[].title / M04 <h3> 一律可反駁的判斷句,禁「第N章 / 影片N」式純章號、禁通用容器詞(章節脈絡/全書脈絡/金句牆/總結/概述…),有效長度 ≥8 字(G8;verify 機攔黑名單+長度,判斷句語義靠蒸餾自查)。腦圖二級節點(v4 批 A 雙層化)例外:topic 改概念關鍵詞 ≤10 字做掃讀層、取消 ≥8 字下限(仍守黑名單+禁容器詞);可反駁判斷句下沉到 tags[0](≥8 字,verify 機攔缺失/過短),tags[1] 放「第N章」章碼 chip(見 method §4.6 / html-spec §5)。
  • 詳實度下限(v2):每章 narrative 書 ≥800 字 / 影片段 ≥400 字(G9);寧可少論點講透,不注水;標誌性案例 / 故事必須整段完整講(時間·人物·動作·轉折·結果),禁壓成一句標籤。
  • 真封面(書,v2):書籍 M01 封面必須真封面 base64(data:image),禁外鏈、禁純色佔位;聯網拿不到才退佔位 SVG。影片用系列封面(首集縮圖 data: URI)。
  • URL:外部資訊(作者/書評/同類書/觀點對比/跨書外部)必須帶可點擊 http(s) 來源 URL;拿不到就降級隱藏,不臆造。
  • 不編造:金句 <blockquote> / excerpts 原文照錄不改寫(直接照錄單段 ≤150 字,blockquote 明示引用,連續 30 字與原文雷同即版權紅線須改寫);拿不到的資料(評分/年份)據實留空,不製造假精度。
  • 破折號一律 --:所有給讀者看的文字裡用兩個英文連字元,禁全形 ——。
  • 底部「回原書」宣告:頁面底部固定 AI 拆書當地圖、別當目的地的收口宣告(骨架已帶,別刪)。

批次模式(蒸多本)

  • 先抽樣 1 本人工驗收再鋪量:多本任務先完整執行 1 本(Step0-7 + 瀏覽器過一遍),你/審校者確認品質與 signature 成立,通過才並行鋪其餘。
  • 6 本/批、批內串行:小批次防服務端 529 Overloaded;一次性高並發會大面積失敗。
  • Pass2 fan-out 是本輪最大成本:v2 蒸餾成本約為 v1 的 2.5-3 倍(第二遍詳實轉述 per-chapter 分組並行 + 三頁搜尋),全程 Opus,預設不做 token 節流;批次鋪量時把每本內部的 Pass2 fan-out 也算進並發預算,別一次性起太多。
  • 以盤上檔案為準:部分「失敗」的 agent 其實已寫盤、只是返回中繼資料時被限流 → 核對 $DATA\{書目錄}\ 實際產物,別只信 workflow 的 succeeded 計數。
  • 索引串行登記:Step4 的 update_index.py register 會寫同一個 knowledge-index.json,批次時串行登記(逐本 dry-run→真跑),避免並發寫盤互相覆蓋;每次寫前自動 .bak。

環境依賴

  • Python:pip install ebooklib beautifulsoup4 pymupdf pillow pytest playwright + playwright install chromium(Step7 需 chromium;pillow 用於真封面 / 縮圖的壓縮與 base64 內聯)。
  • azw3 / mobi 輸入需 calibre 的 ebook-convert(winget install calibre.calibre);epub/pdf/txt 不需要。
  • 影片系列(取材 cascade 見 method.md §V.0):yt-dlp(YouTube 抓字幕 + 抓評論;B站評論走公開 API 免依賴)。B站/抖音的轉寫需一個字幕/ASR 上游工具(如 video-to-subtitle-summary,讀其 AI_DOUYIN_API_KEY);fetch_comments 的 B站評論無需 key。無字幕 / 需畫面語義走一個 Gemini 影片分析工具:本倉兄弟 skill sansheng-gemini-video(讀 env GOOGLE_API_KEY),裝上即可;不裝不影響書籍蒸餾與有字幕影片。

相關技能