name: knowledge-engineering description: "工業級RAG切片工具「可落地、可量化、可最佳化」,將RAG知識庫長文件拆解為語義完整、檢索就緒的原子化知識切片，內建多層質量門禁（校驗→審計→檢索可達性評估），確保切片可用性與RAG檢索命中率。" keywords: [ "rag", "切片", "知識庫", "語義分割", "檢索增強生成", "chunking", "文件拆分", "質量門禁", "embedding-hint", "self-check", "PurePythonEmbedder", "retrieval-evaluation", "cross-refs", ] version: "1.0.13" metadata: domain: "knowledge-engineering" author: "智慧半島" platform: windows: full linux: full macos: full openclaw: requires: bins: - python emoji: "📚"

文件結構：SKILL.md = 核心執行時指令（Agent 執行必讀），REFERENCE.md = 擴充套件參考與運維細節。

📖 分級導航

RAG知識庫原子化切片控制器 (Auto-Archiving & Semantic-Preservation Edition)

🟢 最小可用示例：python scripts/slice_generator.py input.md slices/。完整工作流見 §0-§11。

速查：標準工作流 (Quick Reference)

從原始檔到檢索就緒切片的完整路徑，5 步閉環：

Init-Step-Poll 漸進式防卡死協議

長文件切片、批次知識庫匯入、檢索評估和斷點續傳必須採用 Init → Step → Poll。該協議不替代標準工作流，而是把標準工作流拆成可恢復、可驗證的小步，防止 Token 溢位、長時間生成中斷或部分切片失敗後無法歸因。

執行約束：

• Init 階段只生成計劃和任務狀態，不直接批次寫切片正文。
• Step 階段不得一次性生成全部切片；超大文件每批最多 2 片，普通文件每批最多 5 片。
• Poll 階段完成度只能按“已通過校驗切片數 / 計劃切片數”計算，未校驗切片不得計入完成。
• 出現 Token 溢位、索引跳號、死鏈或檢索死片時，必須先 Poll 當前狀態，再回到對應 Step 修復。
• 最終交付前必須執行 batch_audit.py 和 evaluate_retrieval.py，並輸出審計/檢索驗證證據。

Goal

作為 RAG/知識庫管線的核心 ETL 引擎，將長文件拆解為語義完整、物理隔離、自包含、檢索就緒的 L0 級原子切片。核心使命：在嚴格執行目錄隔離的同時，確保切片既是獨立的檢索單元，又是原文語義的無損投影。

⛔ 核心紅線 (Critical Constraints)

1. 目錄絕對隔離：每個原始檔必須生成同名專屬資料夾。嚴禁任何切片檔案直接存在於輸出根目錄。
2. 語義完整性優先於長度限制：當字數熔斷點位於程式碼塊、表格、步驟列表或邏輯論證中間時，必須延後至當前語義單元結束處切分，禁止截斷原子邏輯。
3. 禁止破壞性改寫：自包含轉換僅允許"補充"和"顯式化"，嚴禁刪除原文技術引數、修改程式碼邏輯或替換專業術語。
4. 零指代原則：切片內不得出現未定義的 this, it, 上述, 如下 等依賴外部上下文的指代詞。
5. 廢棄內容顯式標記：檢測到廢棄聲明後必須在正文首段前強制插入 > [!CAUTION] 警告，並在 YAML 中標記 status: deprecated。若版本號未知，寫"某個版本"並標記 human_review_required: true。
6. 禁止指令碼模板生成後設資料：embedding_hint、qa_pairs、hybrid_keywords、tags 等語義後設資料必須由 Agent 自身推理生成。
7. 禁止外部 LLM API：禁止呼叫任何外部 LLM API 來生成切片內容、摘要或後設資料。
8. 網路驅動器路徑約束：涉及網路驅動器（如 X: 盤、E:\Marvis_Data）上的檔案讀寫時，優先使用 python_executor。
9. 語義保真原則：關鍵數值/引數名/錯誤碼/配置項等事實資料必須原樣出現在切片正文中；隱含假設須顯式化；因果鏈須標註前置條件。
10. 系統破壞操作禁令 (HARB)：對工作目錄外任意路徑的批次寫操作、rm -rf/del /f /s 等遞迴強制刪除、git destructive 操作、資料庫 DROP/TRUNCATE 等命令，必須輸出完整命令預覽並等待使用者顯式確認。

Prerequisites (環境依賴)

一鍵安裝：pip install sentence-transformers numpy pyyaml

0. 預處理思維鏈 (Pre-computation CoT) [強制執行]

在生成任何切片檔案之前，必須先在 <analysis> XML標籤內完成以下推理（此標籤內容不計入最終切片輸出）：

核心四步（必須完成）：

1. 結構掃描 + 原子單元標記：列出所有 H1-H3 標題並識別不可分割的程式碼塊/表格/Mermaid圖/LaTeX公式，標記其起止位置。超長程式碼塊（>50行）判斷是否可按方法/分支再拆分。
2. Token 預算 + 熔斷預演：中文 1 字≈1.5 Token、程式碼 1 字元≈0.3 Token、英文 1 詞≈1.3 Token。按差異化軟上限（純文本 700 字/程式碼 500 字/混合加權計算）模擬切分，檢查是否命中原子單元。
3. 目錄決策 + 版本檢測：確定二級目錄結構（api/config/guide/concepts/misc/multimodal）、降級策略應用結果及完整檔名列表。掃描 deprecated/version 關鍵詞，規劃警告標記位置。
4. 可用性預檢 + 消歧預檢：逐切片預判獨立檢索場景下的可用性（上下文自足/示例可執行/邊界情況），識別同名衝突、語義重疊、泛化詞陷阱並規劃消歧字首。

⚠️ 未完成 <analysis> 直接輸出切片視為嚴重違規。

🛑 STOP CHECKPOINT：<analysis> 完成後必須暫停，將分析結果摘要輸出給使用者確認。確認後開始生成切片檔案。禁止跳過確認直接進入批次生成。

💡 完整 10 步 CoT 細節（含命令有效性預檢、Token 估算公式等）見 REFERENCE.md §1-§2。

1. 動態目錄與路由契約 (Directory & Routing Contract)

1.1 原始檔指紋與後設資料繼承

• Source-ID：取檔名（不含字尾）作為唯一標識。
• 強制動作：建立 {Source-ID}/ 資料夾作為所有輸出的根容器。
• 後設資料繼承：從原始檔 Frontmatter 提取 version, author, last_updated，注入到每個切片的 YAML 頭中。

1.2 二級目錄智慧分類

在 {Source-ID}/ 內部按內容屬性路由：api/（函式簽名/類定義）、config/（配置項說明，與 api/ 互斥）、guide/（操作指南/故障排查）、concepts/（架構原理/術語定義）、misc/（Changelog/FAQ/附錄）、multimodal/（多模態元素 ≥5 且佔比 ≥25% 時建立）。

動態降級規則：某分類下切片數 ≤2 且總字數 <1500 字 → 合併至根目錄，檔名保留分類字首；緩衝區 1300~1700 字按切片數和各片字數綜合判斷。單切片不建子目錄。完整降級策略（含防抖動、結構穩定性）見 REFERENCE.md §1。

1.3 版本演進處理

• 同一 Source-ID 下存在多版本時，自動生成 version_matrix.md 索引切片（含版本差異摘要表）。
• 原始檔缺失或不可讀 → 立即終止，明確報錯，禁止憑空生成。

2. 智慧拆分觸發器 (Smart Splitting Triggers)

採用 "語義優先，字數兜底，回溯保護" 三重判定機制。

字數軟上限：純文本 700 字 / 程式碼 500 字+40 行 / 混合內容加權 (文本字數×1.0 + 程式碼字數×1.4 + 表格單元格數×0.3) / 內容段數。

多模態切分策略、自包含轉換 8 條完整規則見 REFERENCE.md §1-§2。

3. 標準化輸出格式 (Standard Output Format)

每個切片必須嚴格遵循 YAML + Markdown 模板。14 個必填欄位：title, source_id, category, index, version, status, tags, embedding_hint, structural_context, hybrid_keywords, cross_refs, qa_pairs, multimodal_refs, human_review_required。正文必須覆蓋：概念定義 → 使用場景 → 核心內容 → 注意事項 → 相關連結。

完整模板及後設資料欄位精化規則（含 embedding_hint ≤200字 + 實體名、structural_context 格式、hybrid_keywords 泛化詞排除、qa_pairs 唯一性驗證）見 REFERENCE.md §3。

4. 輸出後自檢協議 (Post-Generation Self-Correction)

每個切片寫入磁碟後，必須立即執行校驗。命中任何 🔴 致命項 → 立即重生成該切片直至通過。

4.1 YAML Frontmatter 完整性強制校驗 [最高優先順序]

重新讀取剛寫入的檔案，檢查 14 個必填欄位是否全部存在。若檢測到外部水印覆蓋標準 YAML 塊，必須強制追加第二個 --- 塊寫入完整標準後設資料。校驗失敗立即重寫，禁止延遲處理。

4.2 阻斷式分級自檢

🔴 致命項（必須重生成）：目錄隔離違規 | 語義完整被破壞（程式碼塊/表格/列表截斷） | 零指代違規 | 事實保真失敗（原文關鍵數值/引數/錯誤碼未被保留） | YAML 14 欄位缺失。

完整檢查項（含 🟡 警告 10 項、🟢 建議 3 項、自檢註釋格式）見 REFERENCE.md §4。

5. 分批處理協議 (Token Budget Awareness)

當預估切片數 > 10 或總 Token 接近上下文視窗 70% 時觸發分批。

🔴 CHECKPOINT：觸發分批後必須暫停，先輸出 <analysis> 摘要和切片清單預覽，等待使用者確認後再逐批（每批 3~5 個切片）生成。

每批結束後強制追加批審計註釋（索引連續性/孤立切片/大小異常），全部批次完成後強制執行終結校驗（索引連續性/cross_refs 有效性/廢棄命令檢測）。終結校驗不通過不得聲稱任務完成。

6. 切片完整可用性契約 (Slice Completeness & Usability Contract)

每片生成後逐項自檢五維（必須全部 ✅）：上下文自足性（模組錨定/術語本地定義）、示例可執行性（import 補全/I/O 標註/環境宣告）、知識層級（五段完整）、負面資訊（限制/邊界/陷阱顯式化）、檢索訊號（qa_pairs 覆蓋 how-to/what-is/troubleshooting 三類意圖）。

完整檢查表格（含合規/違規示例）見 REFERENCE.md §4。

7. 語義保真與檢索精度契約 (Semantic Fidelity & Retrieval Precision)

完整驗證規則（含事實型別檢測方法、隱含假設標註格式、消歧策略表）見 REFERENCE.md §5。

8. 複用指令碼體系 (Reusable Scripts)

🩺 症狀→指令碼速查（無需通讀全文）：

標準工作流：slice_generator.py --json → Agent 逐切片填充 → validate_slice.py --fix（每片）→ batch_audit.py（每批/全部）→ evaluate_retrieval.py --fix（終檢）。

各指令碼詳細用法（引數說明、呼叫時機、輸出格式）見 REFERENCE.md §6。

9. 使用指南與能力邊界 (User Guide & Scope)

使用者操作：說"把 xxx.md 切片"即可。Agent 分析 10~30s → 確認計劃 → 逐批生成 → 驗收結果。支援增量追加、先看計劃、從 docx 開始等常見操作。

能力邊界：支援 md/txt/yaml/json/PDF，不支援圖片直接切片/資料庫/動態網頁。完整使用者指南（含實操案例、FAQ）見 REFERENCE.md §7；能力邊界細節見 REFERENCE.md §9；更新記錄見 REFERENCE.md §11。

7w4.net收錄了海量優質技能外掛。

10. 異常處理 (Error Handling)

所有錯誤資訊必須遵循三段式：[型別]: 發生了什麼 → 原因: 為什麼發生 → 操作: 如何修復。

完整異常處理（含靜默失敗防護清單、通俗錯誤速查指南、精確處理命令）見 REFERENCE.md §12。

11. 反模式 (Anti-Patterns)

完整 13 條反模式清單（含症狀診斷、危害說明）及 FAQ 見 REFERENCE.md §8。

12. 平臺相容性 (Platform Compatibility)

Windows / Linux / macOS 三平臺完全支援。關鍵約束：網路驅動器用 python_executor；evaluate_retrieval.py 三層嵌入降級路由（SBERT → 自動安裝 → PurePythonEmbedder）；所有指令碼使用 pathlib.Path。詳見 REFERENCE.md §10。

這個工具質量不錯，能把長文件自動拆成適合 RAG 知識庫檢索的小片段，自帶多層檢查確保切片質量，還能自動評估檢索效果。文件分層清晰，新手有快速入門指南，深入有詳細參考。不足的是說明書本身有點長讀起來費勁，另外對圖片、圖表等多模態內容的處理能力比較有限。總體來說是一款認真做的專業工具，適合需要整理技術文件的使用者使用。