opensearch-skills

OpenSearch 技能

这是 OpenSearch 的顶级技能。它包含四个类别技能，也可以单独安装和使用：

类别	技能	单独安装
搜索	opensearch-launchpad	npx skills add opensearch-project/opensearch-agent-skills@opensearch-launchpad --full-depth
可观测性	log-analytics	npx skills add opensearch-project/opensearch-agent-skills@log-analytics --full-depth
可观测性	trace-analytics	npx skills add opensearch-project/opensearch-agent-skills@trace-analytics --full-depth
云	aws-setup	npx skills add opensearch-project/opensearch-agent-skills@aws-setup --full-depth
云	aiven-setup	npx skills add opensearch-project/opensearch-agent-skills@aiven-setup --full-depth
摄取	document-processing	npx skills add opensearch-project/opensearch-agent-skills@document-processing --full-depth
云	managed-ingestion-service	npx skills add opensearch-project/opensearch-agent-skills@managed-ingestion-service --full-depth

路由

根据用户意图路由到相应技能：

用户意图	技能
构建搜索应用、设置索引、选择搜索策略	opensearch-launchpad
分析日志、使用 PPL 查询、发现错误模式	log-analytics
调查跟踪、调试跨度、分析服务映射	trace-analytics
部署到 AWS、配置域或集合	aws-setup
部署到 Aiven、配置托管式 OpenSearch 服务	aiven-setup
将文档处理为分块（PDF/DOCX → JSONL）	document-processing
通过 OSIS 大规模摄取分块，从 S3 传输到 AOS/AOSS	managed-ingestion-service
一般 OpenSearch 问题	先搜索文档，然后路由到相关技能

如果用户的意图涉及多个技能（例如，“构建搜索应用并将其部署到 Aiven”），请从合适的技能开始，准备好后再切换到下一个技能。

反馈收集（必须遵循）

这适用于此集合中的所有技能——opensearch-launchpad、log-analytics、trace-analytics、aws-setup、aiven-setup、document-processing 和 managed-ingestion-service。无论当前使用哪个技能，都必须遵循这些规则。

每次交互期间，都必须主动收集反馈。这不是可选项——应将其视为工作流的核心部分，而不是事后补充。

规则

1. 持续关注——在整个对话过程中留意失败、困惑和未满足的需求，而不只是对话结束时。
2. 失败时立即提出——任何命令出错或步骤无法正常工作时，在开始排查前立即提出收集反馈。
3. 不确定时提出——如果不确定如何继续，或技能未涵盖用户的请求，请将其标记为潜在缺口，并提出提交反馈。
4. 在自然的阶段节点询问——完成一个主要阶段后（而不只是全部结束时），询问“目前进展是否符合预期？到现在为止遇到什么阻碍了吗？”
5. 结束时务必询问——用户表示已完成或工作流结束时，请求用户给出 1–5 分的评分。
6. 未经同意绝不发送——展示预览并获得明确的“是”后，才能发送。

触发条件

何时	要做什么
命令返回非零退出码或错误	→ 立即询问：“操作失败了。可以记录这条反馈吗？”
用户说“这不是我想要的”/“这让人困惑”/表达沮丧	→ “看来遇到了阻碍。可以记下哪里出了问题吗？”
用户提出你无法完成的请求	→ “目前还不支持此功能。可以将其标记为功能缺口吗？”
需要采用变通方法（某些操作本应更简单）	→ “这比应有的步骤更多。可以将其标记为使用阻碍吗？”
主要阶段完成	→ “目前进展如何？遇到什么问题了吗？”
用户说“完成了”或工作流结束	→ “整体体验如何？（1-5）”

如何提交

需要安装 uv（用于运行 Python 脚本）

1. 撰写反馈（类型 + 上下文）。
2. 向用户展示预览。
3. 询问：“我可以提交这条匿名反馈吗？”
4. 获得同意后：

uv run python scripts/opensearch_ops.py submit-feedback \
  --type <failure|gap|friction|success> \
  --skill <skill-name> \
  --context "<error message, command, what happened>" \
  --comment "<user's words>" \
  --rating "<1-5, for success only>"

反馈类型

• failure — 命令或步骤出错
• gap — 用户需要的功能不受该技能支持
• friction — 工作流令人困惑、速度慢或需要变通方法
• success — 工作流已完成，用户满意

共享资源

所有技能共享以下资源：

• 脚本：scripts/opensearch_ops.py — 用于执行所有 OpenSearch 操作的 CLI
• Docker 启动脚本：scripts/start_opensearch.sh — 启动本地 OpenSearch 集群
• CLI 参考：cli-reference.md — 完整的命令参考及示例
• 搜索构建器 UI：scripts/ui/ — 在端口 8765 上提供服务的 React 前端

bash scripts/start_opensearch.sh
uv run python scripts/opensearch_ops.py <command> [options]
uv run python scripts/opensearch_ops.py --help

可选 MCP 服务

{
  "mcpServers": {
    "ddg-search": {
      "command": "uvx",
      "args": ["duckduckgo-mcp-server"]
    },
    "awslabs.aws-api-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-api-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    },
    "aws-knowledge-mcp-server": {
      "command": "uvx",
      "args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    },
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    }
  }
}

自动安装缺失的 MCP 服务

使用任何 MCP 工具之前，请检查服务是否可用。如果缺失：

1. 找到 MCP 配置文件：
   • Kiro：.kiro/settings/mcp.json
   • Cursor：.cursor/mcp.json
   • Claude Code：.mcp.json
   • VS Code（Copilot）：.vscode/mcp.json
   • Windsurf：~/.codeium/windsurf/mcp_config.json
2. 读取现有配置（或从 {"mcpServers": {}} 开始）。
3. 合并缺失的服务条目。不要覆盖现有条目。
4. 保存并告知用户重启或重新连接 MCP 服务。

解答 OpenSearch 知识问题

uv run python scripts/opensearch_ops.py search-docs --query "<your query>"
uv run python scripts/opensearch_ops.py search-docs --query "<query>" --site docs.aws.amazon.com