一句话：在控制台里用自然语言操作 Easysearch——建索引、写数据、搜文档、做聚合，不用记 DSL，国内可直接跑。

---

一、Easysearch 智能助手能干什么

能力	你说人话	助手做的事
建索引	「建个 demo-products 索引，要有 name、price、category、created_at」	调 create_index，带好 mapping
写数据	「往 demo-products 里写一条：name 无线耳机，price 299」	单条 / 批量写入
查数据	「在 demo-products 里搜带“数码”的」	全文检索，返回结果并解读
看结构	「有哪些索引？demo-products 的 mapping 长什么样？」	list_indices  + get_mapping
做统计	「按 category 聚一下，看每个类有多少条」	terms 等聚合，用中文总结

底层是 Easysearch（兼容 Elasticsearch API），模型用 DeepSeek，Tool Use 负责「理解意图 → 选工具 → 填参数 → 执行 → 把结果说人话」。你只跟中文对话，不碰 DSL。

---

二、Easysearch 智能助手技术栈与流程

• Easysearch：

  国产搜索引擎，兼容 ES REST API，已有 ES 的查询/写入方式都能用。

• DeepSeek：

  国内可注册、价格低、支持 Tool Use，接口兼容 OpenAI，用 OpenAI SDK 即可。

• Tool Use：

  模型返回「要调哪个工具、参数是什么」，你的代码真正发 HTTP 请求；模型不执行，只「下指令」。https://developers.openai.com/api/docs/guides/function-calling

整体流程：

安全边界在你这边：发什么请求、访问哪个集群，全是本地代码控制。

三、Easysearch 智能助手为什么适配这么好？

本项目是一个独立运行的 Node 应用。适配好的原因在下面三点。

1. 工具即能力、标准化声明

所有对 Easysearch 的操作都收敛成 8 个「工具」：每个工具有明确的 name、description 和 parameters（JSON Schema），模型只需要做两件事——选哪个工具、参数填什么。

这种「把领域能力拆成标准单元、由模型按需调用」的思路，和 Cursor Skill（把知识/流程封装成可被 AI 调用的单元）是同一类思想；但这里用的是 Tool Use 的标准化协议（OpenAI 兼容格式），不是 Skill 文档。

https://developers.openai.com/api/docs/guides/function-calling

description 写清楚「何时用、参数含义」，模型就能在合适场景选对工具、填对参数，所以自然语言和实际请求之间「对得上」。

2. API 与协议统一

Easysearch 兼容 Elasticsearch 的 REST API：索引、搜索、聚合、bulk 的端点和请求体格式都是固定的。
工具参数（如 index、query、documents）和 HTTP 请求有一一对应关系，executor 只做「参数 → 请求体 / 路径」的薄一层转换，不依赖模型「自由发挥」，所以稳定、好维护。

3. 理解与执行分离

模型只产出结构化的 tool_calls（工具名 + 参数），真正发请求的是你的代码。

换模型（如从 DeepSeek 换成 Kimi）、加新工具（如慢查询、告警），只改「谁理解」或「有哪些工具」，执行层（executor）可以不动。职责清晰，扩展和排错都简单。

当前项目的「适配好」不依赖 Skill，核心是：Tool 标准化 + Easysearch/ES 接口统一 + 理解与执行分离。

---

四、Easysearch 智能助手环境要求

• Node.js 18+

• 已装 Cursor（或任意能跑 Node 的环境）

• DeepSeek API Key（platform.deepseek.com 注册）

• 本机或远程 Easysearch/Elasticsearch（如 http://127.0.0.1:9200），无认证也可

  

---

五、Easysearch 智能助手项目结构

easysearch-skills/
├── .env              # 敏感配置，勿提交
├── .env.example      # 配置模板
├── .gitignore
├── package.json
├── tools.js          # 工具声明（OpenAI/DeepSeek 格式）
├── executor.js       # 真正调 Easysearch 的执行层
├── index.js          # 主程序：对话循环 + 工具调度
└── test-flow-prompts.md   # 完整测试提示（复制即用）

---

六、Easysearch 智能助手核心实现

6.1 工具定义（tools.js）

8 个工具，分两类：

• 查询：search_documents、aggregate_data、list_indices、get_mapping

• 写入与结构：create_index、put_mapping、index_document、bulk_index

每个工具都是「name + description + parameters（JSON Schema）」。description 写清楚「什么时候用、参数什么意思」，模型才能选对工具、填对参数。

示例（节选）：

{
  name: "create_index",
  description: "创建新的 Easysearch 索引。可指定 settings 和 mappings...",
  parameters: {
    properties: {
      index: { type: "string", description: "索引名称" },
      settings: { type: "object", description: "可选，如 number_of_shards" },
      mappings: { type: "object", description: "可选，字段类型定义" }
    },
    required: ["index"]
  }
}

6.2 执行层（executor.js）

• 用 axios 创建 Easysearch 客户端（baseURL、auth 从 .env 读；无账号密码则不传 auth）。

• executeTool(toolName, toolInput) 里按 toolName 分发到对应函数。

• 查询类：组 ES 兼容的 DSL，POST /_search 或 GET /_cat/indices、/_mapping。

• 写入类：create_index 发 PUT /{index}；put_mapping 发 PUT /{index}/_mapping；单条写 POST /{index}/_doc；批量写拼 NDJSON 发 POST /_bulk。

要点：索引名、文档 id 做 encodeURIComponent；date_histogram 聚合补 calendar_interval；bulk 用 application/x-ndjson。

6.3 主程序（index.js）

• 用 OpenAI SDK 接 DeepSeek（baseURL: 'https://api.deepseek.com'，model: 'deepseek-chat'）。

• 每轮用户输入后：把消息追进 messages，调 chat.completions.create 时带上 tools、tool_choice: 'auto'。

• 若返回里有 tool_calls：解析参数（先去掉 // 注释再 JSON.parse，避免模型偶尔多打注释导致解析失败），调 executeTool，把结果以 role: 'tool' 追回 messages，再请求一次；无 tool_calls 则直接返回模型文本。

• 命令行用 readline 循环「你: / 助手:」；stdin 关闭时不再 prompt，避免管道测试时报错。

---

七、Easysearch 智能助手配置与运行

1. 安装依赖

npm init -y
npm install openai axios dotenv

2. 配置 .env

复制 .env.example 为 .env，按需填写：

DEEPSEEK_API_KEY=sk-xxx
EASYSEARCH_URL=http://127.0.0.1:9200
EASYSEARCH_USER=
EASYSEARCH_PASS=

无认证则 USER/PASS 留空即可。

3. 启动

node index.js

出现「你:」即可用中文发指令。

---

八、Easysearch 智能助手完整测试流程

项目内已提供一整套测试提示，见 test-flow-prompts.md。按顺序在助手里输入，可跑通整条链路：

1. 创建索引 + 指定字段：建 demo-products，带 name(text)、category(keyword)、price(float)、stock(integer)、created_at(date)。

2. 单条写入：写一条「无线耳机」。

3.批量写入：再写三条（机械键盘、办公椅、显示器）。

4. 查看索引与 mapping：列出索引、看 demo-products 的 mapping。

5. 全文检索：搜「数码」或「键盘」。

6. 聚合：按 category 做 terms 聚合。

7. 检索 + 总数：搜「耳机」并确认总文档数。

---

九、Easysearch 智能助手踩坑与注意点

现象	原因	处理
模型不调工具，直接瞎答	没用到工具或 description 不清晰	System 里强调「涉及数据必须用工具」；把各工具的 description 写具体
401	DeepSeek 或 Easysearch 认证失败	检查 API Key、Easysearch 用户名密码；本地无认证则 USER/PASS 留空
JSON.parse 报错	模型在 arguments 里写了注释或多余符号	解析前 replace(/\/\/.*$/gm,'').trim() 再 parse
管道输入后 readline 报错	stdin 关闭后仍调 prompt	用 process.stdin.destroyed 判断，或 catch ERR_USE_AFTER_CLOSE
聚合/写入 400	DSL 或 bulk 格式不对	看 Easysearch 返回的 error 字段；必要时在 executor 里打日志，把请求体拷到控制台调试

---

十、Easysearch 智能助手扩展方向

• 流式输出：


  create 时加 stream: true，前端或终端按 token 流式展示。

• Web 界面：

  用 Express 提供 API，前端一个简单聊天页，把「你/助手」搬到浏览器。

• 换模型：

  同一套 tools/executor，只改 baseURL 和 model，可接 Kimi、百炼、Ollama 等兼容 OpenAI 格式的模型。

• MCP 封装：

  把当前工具封装成 MCP Server，在 Claude Desktop、Cursor 等里复用，不单独跑 Node 脚本。

---

十一、Easysearch 智能助手小结

• 做什么
  

  用自然语言完成 Easysearch 的建索引、写数据、检索、聚合、看 mapping，小白也能上手。

• 怎么做
  

  DeepSeek 做理解与生成，Tool Use 做「选工具+填参」，本地 executor 真正请求 Easysearch。

• 怎么跑
  

  配好 .env，node index.js，按 test-flow-prompts 测一轮即可验证全流程。

项目代码即文档：tools.js 看能力边界，executor.js 看与 Easysearch 的对接方式，index.js 看对话与工具循环。有需要再在此基础上加流式、换模型或做 MCP，都是改少量入口即可。

2026 年国产搜索引擎大盘点：Easysearch 凭什么值得关注？

Grafana 可视化 Easysearch 数据——从数据源接入到大屏实现

漫画图解 Easysearch RAG —— 让大模型拥有“自己知识库”的关键技术

Text2DSL——自然语言转 Elasticsearch / Easysearch DSL 神器