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 §0 | python $SKILL\scripts\convert_book.py "<書檔案>" --outdir "$DATA\{書目錄}"(重轉加 --force) | book.txt / diagnose.json | exit 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.json | build 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 §V | enrich.md(§3 三塊搜尋 pass;§4 豆瓣反爬;影片看 §V) | 聯網檢索(AnySearch → Tavily → WebSearch,工具鏈見 enrich.md §3.4);影片 reviews/views 讀 comments.json | enrich.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.pyexit 3 不生成、連網搜(enrich)不啟、每書頁入口卡整卡刪。 - 出廠驗證:
python $SKILL\scripts\verify_page.py "$DATA\authors\{author_slug}\author.html"; echo "退出碼=$?"(自動識別作者頁走獨立門禁:4 視圖齊 / 零外鏈 / Zero-Hex / lang=zh / 破折號 / 深鏈格式 / 轉向 verdict 一致;exit 0 才算完成)。
硬門禁(三處,不過不許往下走)
- Step0 exit 3 → 停下問使用者:診斷判「需OCR」(掃描版純圖)或「需人工確認」(gb18030 疑似假字/亂碼率>2%)時,不啟動蒸餾、不硬讀、不編內容,把 diagnose 結論報給使用者定奪(補 OCR / 換檔案 / 人工核編碼)。影片系列同理:
build_series.pyexit 3(全部影片都缺轉寫,一個都沒抓到)→ 停下問使用者(補轉寫 / 換影片 / 核 manifest),不拿空語料硬蒸。 - 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。 - 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 影片分析工具:本倉兄弟 skillsansheng-gemini-video(讀 envGOOGLE_API_KEY),裝上即可;不裝不影響書籍蒸餾與有字幕影片。