圖文知識學習 Skill
給一個主題，交付一篇能講清原理的中文知識文章、已經生成並嵌入的解釋圖，以及可追溯的來源和提示詞，儲存到使用者的 Obsidian。
運行前提
宿主需能載入技能或執行本套指令，具備聯網、檔案讀寫和可呼叫的生圖模型。推薦具備這些能力的 Codex / ChatGPT 環境；其他 Agent 可使用已設定的生圖工具。直接寫入本機 Obsidian 還需要本地檔案存取，只有匯出能力時交付文章與圖片並說明入庫缺口。先檢查實際工具，不能僅憑產品名稱認定能力齊全。
選擇輸出形式
- 知識文章：依下方 1–6 步完成資料查證、圖文講解與 Obsidian 入庫。
- 專案圖文 README：先讀 README 工作流，圍繞「能做什麼、產出長什麼樣、如何安裝、第一次怎麼用」組織圖文，儲存在專案中。此形式不要求 Obsidian 設定，也不套用知識長文的篇幅、圖量、YAML 和總結圖要求。查證、寫作與配圖原則繼續複用。
範圍與預設結果
- 完整文章通常約 3000–6000 中文字、3–5 張解釋圖；圖量含結尾綜合總結圖，依主題調整。
- 開頭用淺底色的概念導語交代「是什麼、怎樣工作、解決什麼問題」，保留完整定義；隨後介紹必要背景、動機與由來。
- 圖片預設採用 Jiale 的 AI 工坊風格。正文與圖註就地交代影響理解的條件，圖片直接解釋知識。
- 修訂任務只改使用者指定部分。只調整開頭卡片時，保留正文、配圖、圖註與配圖風格；使用者明確要求重繪後再改圖。
- 在已授權範圍內完成查證、寫作、生成和入庫。缺少影響結果的設定時集中詢問，不把普通版式選擇變成審批。
1. 確定筆記庫與依賴
讀取技能根目錄的 config.local.json（如存在）。本次明確要求優先於設定；設定缺項再使用使用者環境或知識庫指引。欄位見 歸檔規則。缺少目標庫且無法從上下文確定時，只詢問目標庫路徑，先完成獨立的研究與草稿工作。
進入目標庫後，讀取存在的 AGENTS.md、使用指南和首頁；參考同類筆記確定目錄、元資訊與連結方式。依賴 wikilink 內容時開啟實際檔案。
依本階段需要使用以下能力，從當前環境的技能目錄定位，避免寫死安裝路徑：
| 能力 | 優先複用 | 未安裝時 |
|---|---|---|
| 平台搜尋與讀取 | agent-reach；先讀其說明，使用實際可用管道 | 使用宿主可用的唯讀檢索，並說明本次採用的管道 |
| 通用網頁與論文查證 | 宿主聯網工具；可輔以 research-workflow | 直接閱讀一手資料 |
| 寫作與配圖規劃 | 本包規則；可輔以 content-research-writer、baoyu-article-illustrator | 依本包流程完成 |
| 點陣圖生成或編輯 | 宿主可呼叫的生圖工具；有原生 Image / imagegen 時優先使用 | 保留已完成草稿與配圖計劃，明確圖片缺口 |
| 本地入庫 | Python 3.10+、本包歸檔腳本 | 明確缺少環境，保留可遷移的工作檔案 |
這些外部技能不隨本包分發。已有授權覆蓋的步驟繼續執行；遵守宿主工具的真實能力和限制。
2. 查證並建立資料底稿
在本次工作目錄儲存 sources.md：記錄實際開啟的資料、URL、版本或日期、支援的結論與未解決問題。先查官方文件、論文、原始碼和原始發布；平台貼文用於發現線索、實踐經驗或爭議。適合的平台資料優先透過 Agent Reach 取得。
文章中的重要數字、年代、架構和性能結論對應實際讀過的原文。檢索摘要只作為線索；區分事實、推斷、教學算例與實測結果。涉及起源和演變時核對原始來源。依需要讀已有筆記，複用概念並核實連結目標。
完成條件：核心機制和背景均有依據，關鍵分歧已說明，資料足夠支撐文章中的具體例子。
3. 寫出學習主線
讀取 寫作規則，形成帶 YAML frontmatter 的 Markdown 草稿。用完整定義開篇，依「背景與動機 → 整體過程 → 關鍵機制 → 具體例子 → 工程取捨 → 學習收束」組織內容，順序隨主題調整。
在有圖解價值的位置放唯一標記，例如 <!-- figure:01 -->。正文解釋原因和中間推理，圖展示結構、過程或差異；來源連結靠近相應結論。結尾綜合總結圖位於主要講解之後、原始資料列表之前。
完成條件：讀者能解釋因果過程、複述一個例子並判斷適用條件；開頭定義、背景和結尾總結銜接，關鍵結論與資料底稿一致。
4. 規劃並生成配圖
讀取 視覺規範，儲存 illustration-plan.md，列明每張圖的問題、對應段落、節點、連線、數值與圖註。若複用寶玉配圖，將該視覺規範複製到本次目錄的 .baoyu-skills/baoyu-article-illustrator/EXTEND.md。
每張圖的完整最終提示詞儲存為 prompts/01-flow.md 等檔案。依「解釋目的、具體物件和關係、版式、視覺、逐字標籤、畫幅」組織正面描述。使用宿主可呼叫的生圖工具，有原生 Image / imagegen 時優先使用；參數與呼叫方式遵守當前工具規則，通常每批兩張。
從工具結果定位真實檔案，複製到本次工作目錄。逐張開啟檢查術語、中文字、數字、箭頭、比較尺度和可讀性。發現明確錯誤時儲存修訂提示詞並定向修正；保留可用版本，仍有缺口就如實記錄。配圖缺失或未核驗時不能宣稱完整圖文結果。
5. 儲存到 Obsidian
讀取 歸檔規則，儲存 images.json。先對真實草稿、圖片、提示詞和資料記錄執行歸檔腳本的 --dry-run，確認結果後入庫。將技能目錄解析為實際路徑，再呼叫 scripts/archive_note.py，明確傳入目標庫、筆記目錄與附件目錄。
歸檔腳本只新增筆記，同名時建立版本尾碼。修改已有文章時，先備份並依本次授權原位修改；不要重複歸檔出第二篇，也不要讓未改動的圖片重新生成。
需要定義卡片樣式時使用 assets/jiale-knowledge.css；首次安裝樣式只追加該片段，保留使用者已有設定和定製。知識庫存在合適索引時補充一條連結，避免重複。
6. 完成核對
核對最終文章、圖片及檔案是否實際存在，figure 標記是否全部替換，嵌入和 wikilink 是否可解析。檔案檢查、圖中文字審閱和介面預覽分別報告真實驗證範圍。
交付時簡要說明完成內容、儲存位置與實際缺口，附可開啟的筆記或匯出檔案。知識文章只有資料、正文、真實配圖與入庫均完成，才標記為完整交付；專案 README 依對應工作流的完成條件核對。