name: knowledge-safe-merge description: "當用戶要更新、匯入、合併或遷移知識庫/內容庫 JSON 資料，並且需要保留歷史文章、防止整包覆蓋時使用。適用於帶有 articles 陣列的內容站、知識庫站點、靜態 CMS 或簡易後臺。"

Knowledge Safe Merge

適用場景

當用戶提出以下需求時，應優先使用本 Skill：

• “把新的知識庫 JSON 合併進去，不要覆蓋舊文章”
• “匯入一批新文章，但歷史資料必須保留”
• “更新 content/articles 資料來源，先預演再落盤”
• “把舊站內容遷到新站，避免重複或誤覆蓋”
• “做一個安全的 JSON 匯入/更新 SOP”

本 Skill 主要面向這類資料結構：

{
  "categories": [],
  "articles": []
}

其中 articles 是核心，categories 可選。

核心原則

1. 先識別正式資料來源：先找出唯一 authoritative file，再動手。
2. 預設 incoming JSON 可能只是增量：除非已明確驗證是全量，否則禁止直接覆蓋。
3. 先 dry-run，後正式寫入：先看新增/更新/未變化/合併後總數。
4. 先備份，再落盤：正式寫入前保留可回滾版本。
5. 保留歷史文章優先：合併的預設目標是“舊文章不丟”。
6. 上線後必須校驗：驗證 JSON 介面和頁面都正常。

標準工作流

第一步：識別檔案角色

先明確這幾個概念：

• 正式資料來源：站點或系統真正讀取的 JSON 檔案
• 映象檔案：同步副本、人工備份、匯出快照
• incoming 檔案：這次新收到、準備匯入的 JSON

如果使用者沒有說清楚，先查專案程式碼或配置，確認誰才是正式資料來源。

第二步：檢查資料結構

至少確認：

• 根物件是否為 JSON object
• 是否存在 articles 陣列
• 每篇文章是否具備最基本的 title 和 content
• id 是否穩定可用
• 是否存在 date、catId 等輔助欄位

如果結構差異很大，不要強行合併，先給出適配方案。

本技能來自小蔥技能站7w4.net。

第三步：優先使用專案現有指令碼

如果專案裡已經有穩定的合併指令碼、後臺匯入邏輯或資料管道，優先複用專案已有方案。

只有在專案沒有現成方案，或使用者明確希望快速落地一個通用方案時，才使用本 Skill 自帶指令碼：

py -3 scripts/merge_knowledge_json.py --current "正式資料來源.json" --incoming "新資料.json" --dry-run

第四步：確認合併規則

預設規則：

1. 優先按 id 匹配
2. 如果 id 不同，再按“title + date”匹配
3. 未匹配到的文章追加為新文章
4. 合併結果按日期倒序、再按 id 排序

第五步：正式寫入前備份

正式寫入前必須備份當前正式檔案。

如果使用自帶指令碼，可通過 --backup-dir 指定備份目錄；未指定時會自動備份到正式資料來源同級目錄下的 .knowledge-backups/。

第六步：正式執行

典型命令：

py -3 scripts/merge_knowledge_json.py --current "public/knowledge-data.json" --incoming "new.json" --mirror "knowledge-data.json"

如需顯式輸出到另一個檔案：

py -3 scripts/merge_knowledge_json.py --current "current.json" --incoming "incoming.json" --output "merged.json"

第七步：寫入後校驗

至少確認：

• 最終文章總數符合預期
• 新文章能查到
• 關鍵舊文章仍存在
• 如果涉及網站上線，校驗線上 JSON 介面和內容頁

推薦命令模板

僅預演

py -3 scripts/merge_knowledge_json.py --current "current.json" --incoming "incoming.json" --dry-run

正式覆蓋正式資料來源

py -3 scripts/merge_knowledge_json.py --current "public/knowledge-data.json" --incoming "incoming.json"

正式寫入並同步映象檔案

py -3 scripts/merge_knowledge_json.py --current "public/knowledge-data.json" --incoming "incoming.json" --mirror "knowledge-data.json"

寫入自定義輸出檔案

py -3 scripts/merge_knowledge_json.py --current "current.json" --incoming "incoming.json" --output "merged.json"

嚴格禁止

• 禁止把來源不明、數量明顯偏少的 JSON 直接覆蓋正式資料來源
• 禁止把映象檔案、匯出檔案、測試檔案誤當成正式資料來源
• 禁止跳過 dry-run 就直接上線，除非使用者明確接受風險
• 禁止在沒有備份的情況下覆蓋生產內容資料
• 禁止只看“新文章出現了”就結束，必須確認“舊文章還在”

產出要求

處理完後，至少要給出：

1. 本次識別出的正式資料來源路徑
2. incoming 檔案路徑
3. dry-run 或正式執行統計：新增 / 更新 / 未變化 / 合併後總數
4. 是否已備份
5. 是否同步映象
6. 是否完成線上校驗（若有）

資源

• 詳細安裝與分享說明：references/install-and-share.md
• 通用合併指令碼：scripts/merge_knowledge_json.py
• 對外介紹文件：README.md

這個 Skill 質量不錯，文件齊全且寫得清楚易懂，很好地解決了“合併 JSON 不覆蓋舊文章”的痛點。使用流程設計合理，先預覽再執行、預設保留舊資料，讓人用起來比較放心。指令碼支援預覽、備份和同步映象，功能考慮周全。美中不足的是沒有提供示例資料，新手可能需要額外準備測試檔案才能快速上手。整體適合需要定期匯入文章資料的內容站點使用。