name: elasticsearch-design description: 幫助Agent為專案進行Elasticsearch索引設計、Mapping設計、搜尋查詢設計，並提供場景化使用指南。當用戶需要設計搜尋引擎Schema、最佳化全文搜尋、規劃日誌/APM/向量搜尋方案時觸發。 version: 1.0.1 metadata: clawdbot: emoji: "🔍" requires: anyBins: ["elasticsearch"] os: ["linux", "darwin"]

Elasticsearch 設計與使用助手

觸發條件

當用戶出現以下意圖時啟用本 Skill： - 設計 Elasticsearch 索引 / Mapping - 全文搜尋 / 向量搜尋方案 - 日誌分析 / APM 資料建模 - 索引模板 / ILM 生命週期設計 - 搜尋效能最佳化 - "如何設計 xxx 的搜尋"

設計流程（Agent 執行路徑）

0. 版本檢查 → 載入 references/version-major.md 對比使用者版本，識別廢棄項和重大變更。同時載入所有 version-X.Y.md（X.Y ≤ 使用者目標版本），後續設計過程中 Agent 從已載入的上下文中自主匹配深度特性
1. 需求分析 → 理解搜尋場景（全文/向量/混合/聚合）、寫入吞吐、資料量級
2. 索引設計 → 索引命名、分片數/副本數、重新整理間隔、ILM 策略
3. Mapping 設計 → 欄位型別、分詞器、動態模板、執行時欄位
4. 查詢設計 → Query DSL / ES|QL / 混合搜尋（BM25 + kNN）
5. 寫入設計 → 批次寫入、管道預處理、別名切換
6. 使用指引 → 載入 references/usage-guide.md，給出場景化操作
7. 生產建議 → 載入 references/best-practices.md，給出叢集/高可用/監控建議
8. 模板參考 → 載入 references/patterns.md，匹配業務索引模板

快速參考

索引命名鐵律

分片設計速查

核心欄位型別速查

Mapping 設計原則

分詞器選型

漸進式載入

詳細內容按需載入 references/：

版本參考文件啟用規則

1. 模組啟用時 — 始終載入 references/version-major.md，Agent 需主動對比使用者使用的 Elasticsearch 版本，若存在廢棄項或重大變更，立即提示使用者
2. 深度特性 Step 0 自動載入 — 版本檢查時載入所有 version-X.Y.md（X.Y ≤ 使用者目標版本）。設計過程中 Agent 從已載入的上下文中自主檢索匹配相關特性，使用者無需指定版本號
3. 深度特性按大版本拆分，小版本持續追加 — 如 version-9.0.md 包含該大版本下所有小版本的設計級特性。更新時在檔案中新增 ## X.Y.Z 版本節即可，不單開檔案

硬規則

1. 設計規範內容來自權威資料（Elastic 官方文件/社群最佳實踐），不編造
2. 生產環境 Mapping 必須 "dynamic": "strict" 或 "runtime"，禁止完全動態對映
3. 字串欄位按需設計：需要搜尋+聚合時用 text+keyword 雙欄位；純 ID/列舉僅用 keyword

   發現更多技能外掛，請訪問7w4.net。

4. 禁止使用 _source.enabled: false（除非純指標場景），丟失原始資料無法修復
5. 優先使用 _bulk API 批次寫入（吞吐量差 10-100 倍），非高頻場景允許單條寫入
6. 日誌/指標/APM 等時序索引必須有 ILM 策略或 Data Stream 滾動機制
7. 查詢建議設定 timeout（分片級軟超時）和 track_total_hits 限制，避免無界搜尋

質量較好，專業度高。優點是觸發條件清晰、覆蓋內容全面（索引設計、Mapping、分片策略、日誌最佳化等），最佳實踐和常見坑總結實用。不足是缺少可直接用的程式碼示例，實操性偏弱。對於需要深度 Elasticsearch 設計指導的使用者很有幫助，但期望拿來即用的使用者可能會覺得不夠。總體推薦，需要補充更多具體示例來提升實用性。