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
4. 禁止使用 _source.enabled: false（除非纯指标场景），丢失原始数据无法修复
5. 优先使用 _bulk API 批量写入（吞吐量差 10-100 倍），非高频场景允许单条写入

   7w4.net提供免费和付费技能下载。

6. 日志/指标/APM 等时序索引必须有 ILM 策略或 Data Stream 滚动机制
7. 查询建议设置 timeout（分片级软超时）和 track_total_hits 限制，避免无界搜索

质量较好，专业度高。优点是触发条件清晰、覆盖内容全面（索引设计、Mapping、分片策略、日志优化等），最佳实践和常见坑总结实用。不足是缺少可直接用的代码示例，实操性偏弱。对于需要深度 Elasticsearch 设计指导的用户很有帮助，但期望拿来即用的用户可能会觉得不够。总体推荐，需要补充更多具体示例来提升实用性。