概述

1. 这个方案到底是干嘛的？

让AI写代码/做技术规划的时候，不再瞎猜，而是直接用你公司真实的业务数据做决策。

• 以前：AI给你排技术债务优先级，只会看代码乱不乱，完全不知道这个模块影响了多少付费客户、有多少投诉工单；

• 现在：通过这套方案，Claude（AI）能直接去你本地部署的Elasticsearch（ES）里查业务数据，结合代码、需求文档，给你出完全贴合业务的方案。

2. 核心链路

本地ES 9.x存业务数据 → ES Agent Builder生成「查数据的专用智能体」→ 通过MCP通用协议接入Claude Code → 做成Claude的「子代理」→ 写代码时一句话调用，自动查ES数据+出结果

3. 全程分5步走，跟着走不迷路

1. 搞懂核心原理（10分钟，先懂为什么，再动手不踩坑）

2. 本地环境搭建（ES+Kibana+Claude Code，复制粘贴就能装）

3. 10分钟极简试玩（最小配置跑通全流程，先拿到正反馈）

4. 全场景落地（技术债务优先级规划完整案例）

5. 优化避坑指南（省钱、安全、排错全搞定）

---

一、核心原理

1. 什么是子代理？为什么必须用它？

先搞懂核心痛点：AI的「上下文窗口」

大模型的上下文窗口，就像你开会的白板：

• 你每次跟AI说话，都会把白板上所有的内容重新念一遍，AI才能接着你的话往下说；

• 如果你把查数据的草稿、看代码的笔记、改bug的过程全堆在白板上，很快白板就满了：AI会记不住前面的内容、答非所问，而且你每说一句话，都要为整个白板的内容付费（Token成本暴涨）。

子代理就是解决这个问题的「专项助理」

子代理，就是你给Claude配的专项分工助理，每个助理只干一件事，有自己单独的「小白板」（独立上下文窗口）：

• 比如：你配一个「ES数据查询助理」，专门负责去ES里查业务数据；一个「代码规划助理」，专门写开发计划；一个「代码审查助理」，专门查代码问题。

• 每个助理干完活，只把最终结果写到主白板上，中间的草稿、查询过程全留在自己的小白板里，主白板永远干净，AI不会乱、成本也低，还能每个助理只干自己擅长的事，准确率更高。

子代理的4个核心原则

原则	解释	你实操要这么做
上下文隔离	每个助理有自己的小白板，和主白板、其他助理的白板完全不互通	查ES数据的子代理，绝对不要加改代码的工具，避免数据查询被代码内容干扰
专项能力	一个助理只干一件事，不能让一个助理既查数据又改代码	给子代理的职责越单一越好，比如就叫「技术债务ES数据查询助理」，别搞全能型
可复用性	这个助理配好后，你所有项目都能叫它干活	一次配好ES查询子代理，以后所有项目都能直接用，不用重复配置
权限可控	你可以规定助理只能用什么工具、不能碰什么	查ES的助理，只给它「只读查询」的权限，绝对不给删改数据的权限，避免误操作

2. 什么是MCP协议？为什么需要它？

MCP协议（模型上下文协议），你可以理解成AI和外部工具之间的「通用翻译器」。

• 以前：想让Claude查ES里的数据，你要自己写一堆API接口、处理权限、写查询逻辑，非常麻烦；

• 现在：有了MCP协议，ES和Claude之间能直接对话，你只要点几下配置，Claude就能直接调用ES的功能，不用写一行代码。

3. 什么是Elastic Agent Builder？

ES Agent Builder，就是ES给你做的**「傻瓜式智能体生成器」**。

• 你不用写代码，只要告诉它：能查哪些索引、按什么规则查数据、有什么约束，它就自动生成一个能跟ES对话的智能体；

• 这个智能体天生支持MCP协议，一键就能接到Claude里，变成我们上面说的「ES数据查询子代理」。

4. 什么时候用子代理？什么时候直接写查询？

给你一个明确的判断标准，绝对不瞎用：

✅ 必须用子代理的场景

• 需要查多个ES索引，还要把数据关联起来（比如错误日志关联客户付费等级）

• 需要多步查询，上一步的结果决定下一步查什么（比如先查bug的错误量，再查这些错误影响了多少付费客户）

• 需要把ES的数据和本地代码、需求文档结合起来分析

• 不想让查数据的过程污染主代码对话的上下文

❌ 直接写ES|QL单条查询就行的场景

• 就查一个简单的数，比如「上个月总共有多少个错误」

• 单条简单查询，不需要多步关联、不需要和其他数据结合

---

二、环境准备 Checklist

硬性版本要求

软件	最低版本要求	踩坑预警
Elasticsearch	9.2.0 稳定版	Agent Builder在9.2.0才正式发布，9.0/9.1是测试版，功能不全，绝对不能用
Kibana	和ES版本完全一致	比如ES装了9.2.0，Kibana必须也装9.2.0，差一个小版本都会出兼容性问题
Claude Code	2.0.76 及以上	只有这个版本以上才支持完整的子代理和MCP功能
硬件最低要求	4核8G内存	推荐8核16G，避免ES+Kibana本地运行卡死

步骤1：本地ES 9.x安装部署（新手友好版，关闭HTTPS避坑）

新手先装这个极简版，避开HTTPS证书的坑，先跑通流程；生产环境再用安全版配置。

1. 去Elastic官网下载对应系统的 ES 9.2.0 稳定版 安装包，解压到本地无中文路径的文件夹；

2. 打开解压后的 config/elasticsearch.yml 文件，清空原有内容，复制粘贴下面的配置：

   
   # 集群名称，本地测试随便写
   cluster.name: es-local-claude-demo
   # 节点名称
   node.name: es-local-node-1
   # 绑定所有网卡，本地能访问就行
   network.host: 0.0.0.0
   # ES默认端口
   http.port: 9200
   # 本地单节点模式，不用搞集群
   discovery.type: single-node
   # 关闭HTTPS，新手测试用，避免证书坑
   xpack.security.enabled: false
   xpack.security.enrollment.enabled: false
   xpack.security.http.ssl.enabled: false
   xpack.security.transport.ssl.enabled: false
   # 开启Agent Builder必须的跨域配置
   http.cors.enabled: true
   http.cors.allow-origin: ["*"]
   

3. 启动ES服务：

   • Windows：双击 bin\elasticsearch.bat

   • Mac/Linux：终端进入ES文件夹，执行 ./bin/elasticsearch

4. ✅ 验证成功标准：打开浏览器，访问 http://localhost:9200，能看到类似下面的内容，没有报错就是成功：

   
   {
     "name" : "es-local-node-1",
     "cluster_name" : "es-local-claude-demo",
     "version" : {
       "number" : "9.2.0",
       ...
     },
     "tagline" : "You Know, for Search"
   }
   

步骤2：本地Kibana 9.x安装部署（和ES版本完全一致）

1. 下载和ES完全同版本的Kibana 9.2.0安装包，解压到本地无中文路径的文件夹；

2. 打开解压后的 config/kibana.yml 文件，清空原有内容，复制粘贴下面的配置：

   
   # Kibana默认端口
   server.port: 5601
   # 绑定所有网卡
   server.host: 0.0.0.0
   # 本地ES的地址，必须和上面ES的配置一致
   elasticsearch.hosts: ["http://localhost:9200"]
   # 显式开启Agent Builder（9.2.0默认开启，这里加上更保险）
   xpack.agent_builder.enabled: true
   # 跨域配置，MCP对接必须开
   server.cors.enabled: true
   server.cors.allowOrigin: ["*"]
   

3. 启动Kibana服务：

   • Windows：双击 bin\kibana.bat

   • Mac/Linux：终端进入Kibana文件夹，执行 ./bin/kibana

4. ✅ 验证成功标准：打开浏览器，访问 http://localhost:5601，能正常进入Kibana首页，左侧导航栏找到【AI】菜单，里面有【Agent Builder】选项，就是成功。

步骤3：Claude Code安装与MCP功能验证

1. 去Anthropic官网下载 Claude Code 2.0.76+ 桌面版（新手推荐桌面版，MCP配置更简单），安装完成后登录；

2. 验证MCP功能是否正常：

   • 打开Claude Code，底部切换到「Terminal」终端页；

   • 输入命令 claude mcp --help，按回车；

   • ✅ 验证成功：能看到一堆MCP相关的帮助命令，没有报错，就是功能正常。

步骤4：生成ES API Key（给Claude用的访问凭证，最小权限）

这里绝对不能用超级管理员账号，必须给最小权限，避免误删数据！

1. 打开Kibana，左侧找到【开发工具】→【Dev Tools】，进入控制台；

2. 复制粘贴下面的请求，点击运行，生成专属API Key：

   
   POST /_security/api_key
   {
     "name": "claude-code-es-key",
     "expiration": "180d", // 有效期180天，可自己改
     "metadata": {
       "description": "给Claude Code对接ES用的只读API Key"
     },
     "role_descriptors": {
       "claude-es-role": {
         "cluster": [
           "manage_agent_builder", // 管理Agent Builder的核心权限
           "monitor", // 集群监控权限
           "read_security" // 索引元数据读取权限
         ],
         "indices": [
           {
             // 这里写你允许Claude查的索引名称，后面加的索引要在这里补上
             "names": ["customer_data", "error_logs", "support_tickets", "knowledge"],
             // 只给只读权限！绝对不给写/删/改的权限
             "privileges": ["read", "view_index_metadata", "indices:admin/resolve/index"],
             "allow_restricted_indices": false
           }
         ],
         "applications": [
           {
             "application": "kibana-.kibana",
             "privileges": ["feature_agentBuilder.all"],
             "resources": ["*"]
           }
         ]
       }
     }
   }
   

3. 运行成功后，会返回下面的结果，一定要把 encoded 字段的值完整复制保存下来！这个值只显示一次，丢了只能重新生成：

   
   {
     "id": "xxxxxx",
     "name": "claude-code-es-key",
     "api_key": "xxxxxx",
     "encoded": "这里是你的API Key完整值，一定要保存好"
   }
   

4. ✅ 验证API Key有效性：在Dev Tools里运行下面的请求，能正常返回你的权限信息，就是有效：

   
   GET /_security/_authenticate
   {
     "Authorization": "ApiKey 你刚才保存的encoded值"
   }
   

---

三、10分钟极简试玩（先跑通全流程，建立正反馈）

新手先做这个最小版本，不用搞复杂的索引，先确认「Claude能正常调用ES查数据」，再搞完整场景。

步骤1：在ES里建一个测试索引，加几条测试数据

打开Kibana Dev Tools，复制粘贴下面的请求，依次运行：

# 1. 建一个测试索引：用户订单数据
PUT test_order_data
{
  "mappings": {
    "properties": {
      "order_id": { "type": "keyword" },
      "user_name": { "type": "keyword" },
      "order_amount": { "type": "float" },
      "order_time": { "type": "date" },
      "status": { "type": "keyword" }
    }
  },
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  }
}

# 2. 加几条测试数据
POST test_order_data/_bulk?refresh=true
{"index":{}}
{"order_id":"001","user_name":"企业客户A","order_amount":5000.00,"order_time":"2024-05-01T10:00:00Z","status":"已完成"}
{"index":{}}
{"order_id":"002","user_name":"个人客户B","order_amount":99.00,"order_time":"2024-05-02T11:00:00Z","status":"已完成"}
{"index":{}}
{"order_id":"003","user_name":"企业客户C","order_amount":8000.00,"order_time":"2024-05-03T12:00:00Z","status":"已完成"}

步骤2：用Agent Builder建一个ES查询智能体

打开本地终端，复制粘贴下面的curl命令，替换里面的「你的encoded API Key」，运行：

curl -X POST "http://localhost:5601/api/agent_builder/agents" \
  -H "Authorization: ApiKey 你的encoded API Key" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "test-order-query-agent",
    "name": "订单数据查询智能体",
    "description": "专门查询ES里的订单数据，统计订单金额、订单数量，仅支持只读查询",
    "configuration": {
      "instructions": "你只能查询ES里的test_order_data索引，只能执行只读的ES|QL查询，不能做任何修改、删除操作。查询时要按用户的要求，统计订单金额、订单数量等数据，返回结构化的结果。",
      "tools": [
        {
          "tool_ids": [
            "platform.core.execute_esql",
            "platform.core.get_index_mapping",
            "platform.core.search"
          ]
        }
      ]
    }
  }'

✅ 验证成功：运行后返回一堆JSON，里面有你刚才写的id和name，就是创建成功，也可以在Kibana的Agent Builder页面看到这个智能体。

步骤3：把ES智能体通过MCP接到Claude Code

1. 打开Claude Code的终端，复制粘贴下面的命令，替换「你的encoded API Key」，运行：

   
   claude mcp add --transport http es-test-agent http://localhost:5601/api/agent_builder/mcp --header "Authorization: ApiKey 你的encoded API Key"
   

   命令解释：es-test-agent是给这个连接起的名字，后面会用到；本地测试没开HTTPS，不用加–insecure。

2. 验证连接：在Claude终端运行 claude mcp get es-test-agent

✅ 成功标准：能返回3个ES工具的列表，没有报错，就是对接成功。

步骤4：在Claude里创建子代理，测试调用

1. 打开Claude Code，新建一个项目文件夹，在输入框里打 /agents，按回车，打开代理管理面板；

2. 点击右上角【Create new agent】，按下面的步骤一步步选：

   1. 第一步选【Project scope】（必选！只在当前项目生效，不污染其他项目）；

   2. 第二步选【Generate with Claude (recommended)】；

   3. 第三步，在描述框里复制粘贴：专门查询ES里的订单数据，统计订单金额、客户订单情况，仅在需要查询订单业务数据时调用；

   4. 第四步，【Select tools】→ 点【Advanced options】，只勾选刚才MCP对接的3个ES工具，其他所有工具都不选；

   5. 第五步，模型选sonnet（新手用这个就行，平衡成本和能力），点继续；

   6. 最后一步，选个颜色，点确认，Claude会自动生成名为order-data-query的子代理。

3. 测试调用！在Claude输入框里写：

   
   使用order-data-query子代理，帮我查一下test_order_data索引里的总订单金额，以及企业客户的订单占比
   

✅ 成功标准：Claude会自动调用子代理，去ES里查数据，返回你要的统计结果，全程不用你写一句查询语句！

---

四、全场景落地：技术债务优先级规划（完整可复制）

你已经跑通了最小版本，现在来做完整的业务场景：作为技术负责人，2周迭代、2个开发，从技术债务里选3-4个优先级最高的项，完全基于真实业务数据决策。

步骤1：创建完整的业务索引+导入测试数据

打开Kibana Dev Tools，复制粘贴下面的请求，依次运行（每个索引的创建+数据导入都给全了，直接复制就行）：

点击展开 完整索引创建+数据导入代码

1. 客户数据索引 customer_data

PUT customer_data
{
  "mappings": {
    "properties": {
      "user_id": { "type": "keyword" },
      "customer_tier": { "type": "keyword" },
      "company_name": { "type": "text", "fields": { "keyword": { "type": "keyword" } } },
      "mrr": { "type": "float" },
      "joined_at": { "type": "date", "format": "yyyy-MM-dd" }
    }
  },
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  }
}

POST customer_data/_bulk?refresh=true
{"index":{}}
{"user_id":"enterprise_user_01","customer_tier":"enterprise","company_name":"Acme Corp","mrr":2500.00,"joined_at":"2023-01-15"}
{"index":{}}
{"user_id":"enterprise_user_02","customer_tier":"enterprise","company_name":"GlobalTech Inc","mrr":4200.00,"joined_at":"2022-08-20"}
{"index":{}}
{"user_id":"enterprise_user_05","customer_tier":"enterprise","company_name":"DataFlow Systems","mrr":3100.00,"joined_at":"2023-06-01"}
{"index":{}}
{"user_id":"user_001","customer_tier":"free","company_name":"","mrr":0,"joined_at":"2024-03-15"}
{"index":{}}
{"user_id":"user_002","customer_tier":"free","company_name":"","mrr":0,"joined_at":"2024-05-20"}
{"index":{}}
{"user_id":"user_045","customer_tier":"pro","company_name":"SmallBiz LLC","mrr":49.00,"joined_at":"2024-01-10"}
{"index":{}}
{"user_id":"user_089","customer_tier":"pro","company_name":"StartupXYZ","mrr":49.00,"joined_at":"2024-02-28"}

2. 错误日志索引 error_logs

PUT error_logs
{
  "mappings": {
    "properties": {
      "error_id": { "type": "keyword" },
      "module": { "type": "keyword" },
      "error_type": { "type": "keyword" },
      "message": { "type": "text" },
      "user_id": { "type": "keyword" },
      "timestamp": { "type": "date" },
      "stack_trace": { "type": "text" }
    }
  },
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  }
}

POST error_logs/_bulk?refresh=true
{"index":{}}
{"error_id":"err_001","module":"src/auth/refresh.ts","error_type":"AUTH_TOKEN_EXPIRED","message":"Token refresh race condition","user_id":"enterprise_user_01","timestamp":"2024-05-01T10:00:00Z"}
{"index":{}}
{"error_id":"err_002","module":"src/auth/refresh.ts","error_type":"AUTH_TOKEN_EXPIRED","message":"Token refresh race condition","user_id":"enterprise_user_02","timestamp":"2024-05-01T10:05:00Z"}
{"index":{}}
{"error_id":"err_003","module":"src/auth/refresh.ts","error_type":"AUTH_TOKEN_EXPIRED","message":"Token refresh race condition","user_id":"user_001","timestamp":"2024-05-01T10:10:00Z"}
{"index":{}}
{"error_id":"err_004","module":"src/export/csv.ts","error_type":"REQUEST_TIMEOUT","message":"CSV export timeout on large datasets","user_id":"enterprise_user_05","timestamp":"2024-05-01T11:00:00Z"}
{"index":{}}
{"error_id":"err_005","module":"src/export/csv.ts","error_type":"REQUEST_TIMEOUT","message":"CSV export timeout on large datasets","user_id":"user_045","timestamp":"2024-05-01T11:05:00Z"}
{"index":{}}
{"error_id":"err_006","module":"src/export/csv.ts","error_type":"REQUEST_TIMEOUT","message":"CSV export timeout on large datasets","user_id":"user_089","timestamp":"2024-05-01T11:10:00Z"}

3. 支持工单索引 support_tickets

PUT support_tickets
{
  "mappings": {
    "properties": {
      "ticket_id": { "type": "keyword" },
      "module": { "type": "keyword" },
      "user_id": { "type": "keyword" },
      "subject": { "type": "text" },
      "description": { "type": "text" },
      "urgency": { "type": "keyword" },
      "status": { "type": "keyword" },
      "created_at": { "type": "date" }
    }
  },
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  }
}

POST support_tickets/_bulk?refresh=true
{"index":{}}
{"ticket_id":"TK-001","module":"src/auth/refresh.ts","user_id":"enterprise_user_01","subject":"Random user logout issue","description":"Users are randomly logged out during operation, affecting daily work","urgency":"high","status":"open","created_at":"2024-04-28T09:00:00Z"}
{"index":{}}
{"ticket_id":"TK-002","module":"src/auth/refresh.ts","user_id":"enterprise_user_02","subject":"Frequent token expiration","description":"Token expires unexpectedly even when user is active","urgency":"high","status":"open","created_at":"2024-04-29T10:00:00Z"}
{"index":{}}
{"ticket_id":"TK-003","module":"src/export/csv.ts","user_id":"enterprise_user_05","subject":"CSV export timeout","description":"Cannot export data with more than 10k rows, timeout after 30s","urgency":"medium","status":"open","created_at":"2024-04-30T11:00:00Z"}
{"index":{}}
{"ticket_id":"TK-004","module":"src/export/csv.ts","user_id":"user_045","subject":"Export function not working for large datasets","description":"Export fails when I try to download all my data","urgency":"medium","status":"open","created_at":"2024-05-01T12:00:00Z"}

4. 内部知识库索引 knowledge

PUT knowledge
{
  "mappings": {
    "properties": {
      "doc_id": { "type": "keyword" },
      "doc_type": { "type": "keyword" },
      "title": { "type": "text" },
      "content": { "type": "text" },
      "created_at": { "type": "date" },
      "updated_at": { "type": "date" }
    }
  },
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  }
}

POST knowledge/_bulk?refresh=true
{"index":{}}
{"doc_id":"doc_001","doc_type":"roadmap","title":"Q1 2024 Engineering Roadmap","content":"Q1 core priorities: 1. Improve enterprise user experience and stability; 2. Optimize data export performance for large datasets; 3. Strengthen authentication security. All technical debt items related to these priorities should be given high priority.","created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-15T00:00:00Z"}
{"index":{}}
{"doc_id":"doc_002","doc_type":"engineering_standard","title":"Authentication Security Standards","content":"All authentication-related code must follow the latest security standards. Token refresh logic must be race-condition free, as it directly affects user data security and enterprise customer trust. Any issues in authentication modules must be fixed with the highest priority.","created_at":"2023-12-01T00:00:00Z","updated_at":"2024-02-01T00:00:00Z"}

步骤2：创建项目本地文件

在你Claude的项目文件夹里，新建2个Markdown文件，直接复制下面的内容：

1. TECH_DEBT.md（技术债务清单）

# Tech Debt Items
## AUTH-001: Token refresh race condition
- **Module**: src/auth/refresh.ts
- **Symptom**: Users randomly logged out due to token refresh race condition, throwing AUTH_TOKEN_EXPIRED error unexpectedly
- **Estimate**: 3 days
- **Dependencies**: None

## EXPORT-002: CSV export timeout on large datasets
- **Module**: src/export/csv.ts
- **Symptom**: Request timeout after 30s when exporting datasets with more than 10k rows
- **Estimate**: 2 days
- **Dependencies**: None

## API-003: Unoptimized database query in user list endpoint
- **Module**: src/api/users.ts
- **Symptom**: Slow response time (>2s) when loading user list for admin users
- **Estimate**: 2 days
- **Dependencies**: None

## UI-004: Outdated component library version
- **Module**: src/components/
- **Symptom**: Multiple UI bugs and inconsistent styles, missing accessibility features
- **Estimate**: 5 days
- **Dependencies**: None

## LOG-005: Inconsistent log format across services
- **Module**: src/utils/logger.ts
- **Symptom**: Logs are not standardized, making it difficult to aggregate and analyze in Elasticsearch
- **Estimate**: 3 days
- **Dependencies**: None

## AUTH-006: Missing rate limiting on login endpoint
- **Module**: src/auth/login.ts
- **Symptom**: No rate limiting on login requests, risk of brute force attacks
- **Estimate**: 1 day
- **Dependencies**: None

2. REQUIREMENTS.md（Q1需求与迭代约束）

# FlowDesk Q1 2024 Requirements
## Core Business Priorities
1. **Enterprise Customer Retention**: All work must prioritize the stability and experience of enterprise tier customers, who contribute 90% of our revenue.
2. **Security Compliance**: Authentication and authorization related issues must be addressed as top priority to meet compliance requirements.
3. **Performance Optimization**: Core business functions (data export, user management) must have response time under 1s for 99% of requests.
4. **Technical Debt Reduction**: Reduce high-impact technical debt items that affect core business metrics.

## Sprint Constraints
- Sprint duration: 2 weeks
- Available developers: 2
- Maximum items that can be completed: 3-4
- Must align with Q1 2024 roadmap priorities

步骤3：创建技术债务分析专用Agent Builder智能体

打开本地终端，复制粘贴下面的curl命令，替换你的encoded API Key，运行：

curl -X POST "http://localhost:5601/api/agent_builder/agents" \
  -H "Authorization: ApiKey 你的encoded API Key" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "tech-debt-advisor",
    "name": "技术债务优先级分析智能体",
    "description": "通过分析ES里的错误日志、支持工单、客户数据、内部知识库，给技术债务做优先级排序，仅支持只读查询",
    "avatar_color": "#BFDBFF",
    "avatar_symbol": "TD",
    "configuration": {
      "instructions": "你只能查询本地ES里的这4个索引：knowledge、error_logs、support_tickets、customer_data，只能执行只读操作，绝对不能修改/删除数据。\n\n分析技术债务时，必须严格按这个流程执行：\n1. 针对每个技术债务对应的模块，查error_logs里近30天的错误次数、受影响的用户数；\n2. 把受影响的用户和customer_data关联，统计受影响的企业付费客户数量、对应的总营收；\n3. 查support_tickets里对应模块的工单数、紧急程度；\n4. 查knowledge索引，看这个模块是否符合Q1 roadmap优先级、是否违反安全规范；\n5. 把以上所有数据合成，给每个技术债务打1-10分的业务影响分，输出优先级排序。",
      "tools": [
        {
          "tool_ids": [
            "platform.core.search",
            "platform.core.list_indices",
            "platform.core.get_index_mapping",
            "platform.core.get_document_by_id",
            "platform.core.execute_esql",
            "platform.core.generate_esql"
          ]
        }
      ]
    }
  }'

✅ 运行成功后，会返回智能体的详细信息，Kibana的Agent Builder页面也能看到。

步骤4：MCP对接Claude Code

如果之前已经加过MCP，这里不用重复加；如果没加，执行下面的命令：

claude mcp add --transport http tech-debt-agent http://localhost:5601/api/agent_builder/mcp --header "Authorization: ApiKey 你的encoded API Key"

验证：执行 claude mcp get tech-debt-agent，能看到6个ES工具，就是成功。

步骤5：创建Claude子代理（2种方式，新手选图形化）

方式一：图形化创建（新手首选，点点就行）

1. 打开Claude Code的项目，输入 /agents 回车，打开代理面板；

2. 【Create new agent】→ 选【Project scope】→ 【Generate with Claude】；

3. 描述框里复制粘贴：专门对接本地ES的技术债务分析子代理，查询ES里的错误日志、客户数据、工单、知识库，分析技术债务的业务影响，输出优先级建议，仅在需要分析技术债务优先级时调用；

4. 【Select tools】→【Advanced options】，只勾选刚才MCP对接的6个ES工具，其他所有工具都不选；

5. 模型选opus（复杂推理用这个更准），点继续，选个颜色，确认创建，Claude会自动生成名为tech-debt-analyzer的子代理。

方式二：手动配置文件创建（进阶，可版本管理）

1. 进入Claude项目的配置文件夹：

   • Mac/Linux：~/.claude/projects/你的项目名称/agents/

   • Windows：%USERPROFILE%.claude\projects\你的项目名称\agents\

2. 新建 tech-debt-analyzer.agent.md 文件，复制粘贴下面的内容，保存后重启Claude Code即可加载：

   
   ---
   name: tech-debt-analyzer
   description: 专门对接本地ES的技术债务分析子代理，查询ES里的错误日志、客户数据、工单、知识库，分析技术债务的业务影响，输出优先级建议，仅在需要分析技术债务优先级时调用
   tools: platform.core.execute_esql, platform.core.search, platform.core.get_index_mapping, platform.core.list_indices, platform.core.get_document_by_id, platform.core.generate_esql
   model: opus
   permissionMode: ask
   ---
   你是专门的技术债务业务影响分析子代理，只能通过ES工具查询本地ES集群里的业务数据，不能使用其他任何工具。
   你的核心职责：
   1. 严格按照预设的5步流程，查询ES里的4个指定索引，获取技术债务对应的业务数据；
   2. 所有查询必须指定近30天的时间范围，禁止全索引扫描；
   3. 只能执行只读查询，绝对不能执行任何写入、修改、删除操作；
   4. 最终输出结构化的优先级报告，包含每个技术债务的业务影响评分、核心依据、推荐优先级。
   

步骤6：端到端测试与落地

测试1：优先级分析

在Claude输入框里写：

基于TECH_DEBT.md里的技术债务清单，我们有2周迭代、2个开发，需要选3-4个优先级最高的项。
请使用tech-debt-analyzer子代理，查询近30天的错误频率、受影响的企业客户数量、支持工单数、和Q1 roadmap的对齐情况，输出结构化的优先级分析报告，包含每个项的评分、核心依据、推荐优先级。

✅ 成功效果：Claude会自动调用子代理，执行多步ES查询，关联4个索引的数据，最终给你输出一份完全基于真实业务数据的优先级报告，比如会把「AUTH-001 认证模块竞态问题」排在第一位，因为它影响了付费企业客户、有高紧急工单、符合Q1安全优先级。

测试2：全流程开发规划（中心辐射编排模式）

基于REQUIREMENTS.md里的Q1需求和迭代约束，使用planning子代理创建详细的技术债务修复实施计划。
要求：
1. 用tech-debt-analyzer子代理查询ES业务数据，确定优先级最高的技术债务项；
2. 用explore子代理扫描本地代码库，分析每个选中项的代码复杂度和修复风险；
3. 基于2周2个开发的约束，制定详细的每日实施计划，包含任务拆分、依赖关系、验收标准；
4. 所有计划必须完全基于真实的业务影响数据，不能主观假设。

✅ 成功效果：Claude会作为项目经理，并行调用ES查询子代理和代码扫描子代理，汇总所有结果，给你输出一份可直接落地的迭代开发计划。

---

五、核心优化技巧&常见踩坑排查指南

1. Token成本优化（省钱必看）

• 工具最小化：子代理只加必须的工具，工具定义会占用大量Token，多余的工具会让成本暴涨；

• 模型选型：简单查询用haiku，常规分析用sonnet，复杂多步推理用opus，不要全用opus；

• 上下文精简：子代理的系统提示词只写核心规则，不要写废话；要求ES查询只返回必要字段，不要全量返回；

• 上下文隔离：无关任务用独立子代理，不要把所有内容都堆在主对话里，主对话越长，每次调用的成本越高。

2. 安全加固最佳实践

• 权限最小化：API Key只给必要的只读权限，绝对不用超级管理员账号；子代理的permissionMode生产环境设为ask，每次调用前都要你确认；

• 操作约束：在子代理的系统提示词里，明确禁止写入/修改/删除操作，只允许只读查询；

• API Key管理：设置合理的有效期，定期轮换，不用永久有效的API Key；

• 网络隔离：生产环境的ES集群，只允许Claude所在的机器访问，绝对不要对公网暴露。

3. ES性能优化

• 索引优化：日志类索引按天/周分片，查询时必须指定时间范围，避免全索引扫描；

• 字段优化：用于过滤、聚合的字段（module、user_id等）必须设为keyword类型，不要用text类型；

• 查询优化：要求子代理生成的ES|QL必须加limit、精准的where条件，禁止select *。

4. 常见踩坑排查（90%的问题都在这里）

问题	排查步骤+解决方案
MCP连接失败	1. 检查Kibana是否正常运行，localhost:5601能不能访问；2. 检查API Key是否正确、有没有过期；3. 检查ES和Kibana的跨域配置是否开启；4. 如果开了HTTPS，命令里要加–insecure关闭证书校验
子代理不调用ES工具	1. 检查子代理的tools里有没有选对ES工具；2. 检查子代理的描述是否清晰，必须明确写「仅在需要查询ES业务数据时调用」；3. 用显式调用，直接写「使用xxx子代理」，不要用隐式调用
ES查询报权限错误	1. 检查API Key的权限配置里，有没有加对应的索引名称；2. 检查API Key有没有给read权限；3. 验证API Key是否有效，有没有过期
Claude找不到子代理	1. 检查子代理是不是选了【Project scope】，只能在当前项目用；2. 输入/agents，看子代理是不是在列表里；3. 重启Claude Code，重新加载子代理
子代理返回的结果不对	1. 检查子代理的系统提示词里，有没有明确指定索引名称、查询流程；2. 看子代理的执行日志，是不是查错了索引；3. 给子代理的指令要精准，不要模糊描述

---

六、总结

1. 子代理的核心价值，是通过上下文隔离+专项分工，解决AI对话上下文膨胀、答非所问、Token成本高的痛点，让AI的能力更聚焦、更精准；

2. Elastic Agent Builder + MCP协议，彻底打通了Claude和本地ES的壁垒，让AI写代码/做规划的时候，能直接用上你真实的业务数据，不再是「纸上谈兵」；

3. 这套方案的核心是「最小权限、单一职责」，子代理的职责越单一、权限越小，效果越好、越安全；

4. 哪怕你是新手，也能先通过10分钟极简版本跑通全流程，再逐步落地完整的业务场景，完全不用写复杂的代码。