概念熔爐
Concept Forge 將使用者零散的問題轉化為持久的概念資產:一個精簡的解答、一張結構化的知識卡片、一份 Quarkdown 閱讀稿、一份 Slidev 簡報稿,以及一個完全自含的互動式 HTML 解釋頁。
目標不是產生一次性答案。目標是讓概念更容易記住,並隨著時間建立可重複使用的本地知識 / HTML 函式庫。
核心流程
務必依此順序進行:
- 正規化問題:識別核心概念、別名、比較對象和使用者意圖。
- 先查找現有條目:使用
scripts/concept_forge.py lookup。 - 規劃深度:使用
scripts/concept_forge.py plan或研究方法:選擇 Quick、Standard 或 Deep。 - 重複使用,避免重建:如果找到高度相符的結果,直接回傳現有的直接答案和 HTML 路徑。僅在使用者要求、條目過時或概念有時效性時才重新整理。
- 依選擇的深度進行研究(若無可用條目):使用下方的概念透鏡,當主題可能已改變或需要精確來源時進行瀏覽。
- 打造概念記錄:依照
references/concept-schema.md產生結構化的 JSON。 - 渲染與儲存:使用
scripts/concept_forge.py upsert;此步驟必須建立 JSON、Quarkdown、Markdown、HTML 和 Slidev 原始檔。 - 檢查交付分支:如果使用者要求正式閱讀、PDF、簡報、演講、預覽、建置或匯出,請使用
scripts/concept_forge.py bootstrap "<原始請求>"。 - 驗證:使用
scripts/concept_forge.py validate驗證儲存的條目和產生的成品。 - 以中文回報:永遠先給答案,再給本地 HTML 路徑。除非被問到,否則避免提到實作細節。
使用者端回應樣式
每個完成的請求都必須回傳兩件事,依此順序:
- 直接答案:1-3 句簡短的中文句子,立即回答使用者的問題。當有助於記憶時,優先使用生動的比喻。這應能獨立閱讀,讓沒時間打開 HTML 的使用者也看得懂。
- 互動式 HTML:產生或重複使用的 HTML 解釋頁的本地路徑或連結。
使用緊湊的格式,例如:
一句話說,Skill 像給 AI 準備的一本小手冊:Prompt 是這次怎麼做,Skill 是以後遇到同類任務都按這套做。
互動頁:<path/to/html>
不要讓使用者為了獲得基本答案而必須打開 HTML。
工作區
預設工作區:
<current working directory>/concept-forge-workspace
如果使用者指定了其他儲存位置,則使用該位置。首次使用前進行初始化:
python <skill>/scripts/concept_forge.py init --workspace <workspace>
工作區包含:
knowledge/index.json
knowledge/concepts/<slug>/concept.json
knowledge/concepts/<slug>/concept.qd
knowledge/concepts/<slug>/concept.md
knowledge/concepts/<slug>/sources.json
html/<slug>.html
slidev/<slug>/slides.md
slidev/<slug>/package.json
quarkdown/
assets/
config.json
概念透鏡
借用 hv-analysis 的精神,但保持輕量且以概念為規模。
對於每個新概念或重新整理的概念,回答以下層面:
- 一句話記憶:最簡短有用的定義。
- 直接答案:適合聊天的解釋,通常一段,可以加個比喻。
- 它是什麼:白話文解釋。
- 為何存在:是什麼問題、困惑、工作流程或歷史轉變創造了對它的需求。
- 如何運作:理解它所需要的最低限度機制。
- 它不是什麼:常見的誤解和界線。
- 橫向比較:常被混淆的鄰近概念、工具、提示詞、工作流程或術語。
- 關聯地圖:上層概念、同層概念、下層概念、先備知識和後續問題。
- 範例:一個具體的日常情境。
- 記憶鉤子:有助於記憶的比喻、片語或視覺錨點。
- 小測驗:2-3 個輕量問題以強化記憶。
當事實可能具有時效性、專業性、爭議性、產品特定性或來源敏感性時,請使用網路研究。優先採用官方文件和第一手來源。若未進行瀏覽,請在記錄中誠實標示來源為「模型推導 / 使用者提供 / 本地脈絡」。
輸出模式
分支選擇
共有三個產品分支。請精確區分。
- 一般概念分支:使用者問「X 是什麼」、「X 跟 Y 有什麼不同」、「幫我理解 / 記住 / 整理這個概念」,或給出一個關鍵字。產生直接答案、Quarkdown 原始檔、Slidev 原始檔、HTML 和索引。不要提示安裝 Quarkdown 或 Slidev。
- 正式閱讀分支:使用者要求「正式閱讀」、「長文件」、「報告」、「PDF」、「文件」、「列印」、「編譯」、「匯出」、「交付」,或明確提及 Quarkdown。在編譯前執行
bootstrap。如果缺少 Quarkdown,在編譯 / 匯出之前停止,並顯示安裝指引。 - 正式簡報分支:使用者要求「演示」、「公開講解」、「課件」、「幻燈片」、「PPT」、「slides」、「deck」、「presentation」、「預覽」、「建置」、「匯出」,或明確提及 Slidev。在預覽 / 建置 / 匯出前執行
bootstrap。如果缺少 Node/npm 或 Slidev 專案相依套件,在預覽 / 建置 / 匯出之前停止,並顯示設定指引。
如果使用者同時要求閱讀和簡報,則以 Quarkdown 作為母稿,Slidev 作為衍生的演講稿,然後檢查兩個分支。
分支輔助指令:
python <skill>/scripts/concept_forge.py --workspace <workspace> plan "<原始請求>"
python <skill>/scripts/concept_forge.py --workspace <workspace> bootstrap "<原始請求>"
python <skill>/scripts/concept_forge.py --workspace <workspace> bootstrap --intent quarkdown
python <skill>/scripts/concept_forge.py --workspace <workspace> bootstrap --intent slidev
python <skill>/scripts/concept_forge.py --workspace <workspace> bootstrap --intent all
現有條目
如果查找找到高度相符的現有條目:
- 說明該條目已存在。
- 提供
direct_answer中的簡短答案;若無,則使用summary加上memory_hook。 - 提供本地 HTML 頁面的連結。
- 僅在有用的情況下提供可重新整理的項目;預設不重建。
新條目
對於新概念:
- 依照
references/concept-schema.md建立 JSON 記錄。 - 至少包含:標題、別名、深度、直接答案、摘要、它是什麼、為何存在、它不是什麼、比較、關聯、記憶鉤子、測驗、來源。
- 執行:
python <skill>/scripts/concept_forge.py upsert --workspace <workspace> --input <concept.json>
python <skill>/scripts/concept_forge.py validate --workspace <workspace> --slug <slug>
- 先回傳直接答案,再回傳產生的 HTML 路徑。僅在使用者詢問檔案、閱讀稿、演講稿、匯出或除錯時,才提及 Quarkdown 或 Slidev 路徑。
重新整理
僅在以下情況重新整理:
- 使用者要求更新 / 重做 / 擴充;
- 條目年齡超過
refresh_policy.days; - 主題具有時效性或快速變動;
- 來源薄弱或遺失;
- 使用者提出了更具體的後續問題,改變了概念的範圍。
重新整理時,除非明顯錯誤,否則保留現有的別名和關聯連結。
HTML 需求
使用 references/html-explainer.md 取得確切的產品樣式。
產生的頁面必須自含,且必須包含:
- 主標題定義;
- 「它是什麼 / 為何存在 / 它不是什麼」區段;
- 比較卡片;
- 關聯概念地圖;
- 時間軸或起源時間軸(若有幫助);
- 互動式揭示卡片;
- 小測驗;
- 「三件要記住的事」;
- 來源 / 更新頁尾。
該頁面應能在沒有聊天記錄的情況下理解。
一級 Quarkdown 和 Slidev
Quarkdown 和 Slidev 是產品樣式的一部分。
- 永遠產生
concept.qd作為 Quarkdown 母稿。它是知識庫的標準閱讀文件。 - 永遠產生
slidev/<slug>/slides.md作為簡報稿。它是從概念記錄和母稿中提取出來的。 - 永遠產生
html/<slug>.html作為快速的互動式記憶介面。 - 使用動態深度來決定要加入多少研究、來源和修飾:
- Quick:穩定的小型概念;產生所有原始成品,通常跳過編譯 / 匯出。
- Standard:工具、方法、比較和「X 是什麼」的預設值;產生所有成品並驗證結構。
- Deep:使用者要求研究,或主題具有時效性 / 複雜性;加強來源、歷史、橫向比較和演講結構。
- 僅在請求進入正式分支時編譯 Quarkdown 或建置 / 匯出 Slidev。原始碼的產生不得依賴於已安裝的 CLI。
- 首次使用時執行
scripts/concept_forge.py doctor進行一般環境檢查。 - 在正式編譯 / 匯出前執行
scripts/concept_forge.py bootstrap "<原始請求>",以決定是否引導安裝。 - 對於 Quarkdown 正式閱讀,需要
quarkdown。若在 Windows 上遺失,顯示:irm https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.ps1 | iex,然後用quarkdown doctor get install-dir驗證。 - 對於 Quarkdown 編譯,當
quarkdown可用時,執行quarkdown c <concept.qd> --strict --out <verify-dir>。 - 對於 Slidev 正式簡報,需要 Node 加上 npm 或 pnpm。在
slidev/<slug>下,視需求執行npm install或pnpm install,然後執行npm run dev、npm run build或npm run export。 - 對於 Slidev PDF/PPTX 匯出,先在產生的簡報專案中安裝
playwright-chromium:npm i -D playwright-chromium。
品質關卡
在回報完成前,檢查:
- 在建立之前已嘗試過查找;
- 最終回應同時包含直接答案和 HTML 路徑;
- 概念有清晰的「一句話記憶」;
- 涵蓋了鄰近概念和誤解;
- HTML 存在且非空;
- Quarkdown 母稿存在;
- Slidev 原始檔存在;
- 正式分支在編譯 / 匯出前已執行
bootstrap; - 在嘗試編譯 / 匯出前已回報缺少正式工具;
validate通過;- 索引包含標題、別名、slug、直接答案、摘要、Quarkdown 路徑、Slidev 路徑和 HTML 路徑;
- 最終答案簡短、使用中文且面向使用者。
參考資料
references/concept-schema.md:JSON 和 Markdown 記錄樣式。references/research-method.md:輕量 hv-analysis 改編版。references/html-explainer.md:互動式 HTML 產品規格。