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，匹配业务索引模板
快速参考
索引命名铁律
| 规则 | 示例 | 反例 |
|---|
| ------ | ------ | ------ |
格式：<项目>-<数据类型>-<时间粒度> | app-logs-2026.06 | logs |
| 小写+连字符 | ecom-products-v1 | ecom_Products_V1 |
| 按时间滚动必须带日期后缀 | metrics-system-2026.06.09 | 固定索引名 |
| 版本后缀（别名指向当前版本） | search-products-v2（别名 search-products） | 别名混乱 |
分片设计速查
| 维度 | 推荐值 | 说明 |
|---|
| ------ | -------- | ------ |
| 主分片数 | 1（优先按单分片 10-50GB 计算） | 分片数过多导致开销，过少限制并行度 |
| 单分片大小 | 10-50GB | 超过 50GB 考虑拆分索引或增加分片 |
| 副本数 | 1（生产）/ 0（开发） | 至少 1 个副本保高可用 |
| 每 GB 堆的分片数 | ≤ 20 | 每个节点不超过 1000 个分片 |
核心字段类型速查
| 类型 | 使用场景 | Mapping 示例 |
|---|
| ------ | --------- | ------------- |
text | 全文搜索（会分词） | "type": "text", "analyzer": "ik_max_word" |
keyword | 精确匹配/聚合/排序 | "type": "keyword" |
long / integer | 整数 | "type": "long" |
float / double / scaled_float | 小数；金额用 scaled_float | "type": "scaled_float", "scaling_factor": 100 |
boolean | 布尔值 | "type": "boolean" |
date | 时间（ISO 8601 / epoch） | "type": "date", "format": "yyyy-MM-dd HH:mm:ss" |
geo_point | 经纬度坐标 | "type": "geo_point" |
dense_vector | 向量嵌入（kNN 搜索） | "type": "dense_vector", "dims": 1536, "index": true |
object | 嵌套 JSON 对象 | "type": "object" |
nested | 独立索引的对象数组 | "type": "nested" |
ip | IP 地址 | "type": "ip" |
binary | Base64 二进制 | "type": "binary" |
Mapping 设计原则
| 原则 | 说明 |
|---|
| ------ | ------ |
| 禁止动态 Mapping 到生产 | "dynamic": "strict" 或 "runtime" |
| 字符串双字段 | 需要搜索+聚合时为 text+keyword；纯 ID/枚举用 keyword |
| 关闭不必要的 norms/index | "norms": false、"index": false 减少存储 |
| 避免 field explosion | flattened 类型处理高基数不可预知的 Key |
| 运行时字段替代 Script | runtime_mappings 定义计算字段，不占存储 |
分词器选型
| 语言/场景 | 分词器 | 说明 |
|---|
| ---------- | -------- | ------ |
| 中文 | ik_max_word（索引）/ ik_smart（搜索） | 需安装 IK 插件 |
| 英文 | standard / english | 内置 |
| 多语言 | 独立字段 + 不同分词器 | 每个语言一个 text 子字段 |
| 拼音搜索 | pinyin 插件 | 中文拼音混合搜索 |
| 不分词 | keyword 类型 | 精确匹配用 |
渐进式加载
详细内容按需加载 references/：
| 主题 | 文件 | 何时加载 |
|---|
| ------ | ------ | --------- |
| 索引/Mapping/字段/分词设计规范 | references/design-spec.md | Step 2-3 索引和 Mapping 设计 |
| 场景化操作（创建索引/搜索/聚合/别名/ILM） | references/usage-guide.md | Step 6 使用指引 |
| 最佳实践（分片/集群/写入/查询/监控/运维） | references/best-practices.md | Step 7 生产建议 |
| 业务索引模板（6类业务完整Mapping+配置） | references/patterns.md | Step 8 模板参考 |
| 重大版本特性（废弃/依赖变更/新模块） | references/version-major.md | Step 0 版本检查（模块激活时即加载） |
| 深度版本特性 — 9.x（Workflows / ES\ | QL 增强 / PromQL / GPU 向量 / FIPS） | references/version-9.0.md | Step 0 版本检查时自动加载（版本 ≤ 用户目标版本时） |
| 深度版本特性 — 8.x（向量搜索 / ILM / SLM / Data Streams / ES\ | QL） | references/version-8.0.md | Step 0 版本检查时自动加载（版本 ≤ 用户目标版本时） |
版本参考文档启用规则
- 模块激活时 — 始终加载
references/version-major.md，Agent 需主动对比用户使用的 Elasticsearch 版本，若存在废弃项或重大变更，立即提示用户 - 深度特性 Step 0 自动加载 — 版本检查时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本）。设计过程中 Agent 从已加载的上下文中自主检索匹配相关特性，用户无需指定版本号
- 深度特性按大版本拆分，小版本持续追加 — 如
version-9.0.md 包含该大版本下所有小版本的设计级特性。更新时在文件中新增 ## X.Y.Z 版本节即可，不单开文件
硬规则
- 设计规范内容来自权威资料（Elastic 官方文档/社区最佳实践），不编造
- 生产环境 Mapping 必须
"dynamic": "strict" 或 "runtime"，禁止完全动态映射 - 字符串字段按需设计：需要搜索+聚合时用
text+keyword 双字段；纯 ID/枚举仅用 keyword - 禁止使用
_source.enabled: false（除非纯指标场景），丢失原始数据无法修复 - 优先使用
_bulk API 批量写入（吞吐量差 10-100 倍），非高频场景允许单条写入 - 日志/指标/APM 等时序索引必须有 ILM 策略或 Data Stream 滚动机制
- 查询建议设置
timeout（分片级软超时）和 track_total_hits 限制，避免无界搜索