false00/pi-elasticsearch

# @false00/pi-elasticsearch [](https://github.com/false00/pi-elasticsearch/actions/workflows/ci.yml) [](LICENSE) 为 Pi 编程代理打造的面向生产的 Elasticsearch 自动化工具。 `@false00/pi-elasticsearch` 暴露了 **142 个 Pi 工具**，涵盖搜索、日志调查、文档 CRUD、批量操作、索引、集群管理、安全、采集、快照、生命周期、任务、SQL/ESQL、转换、推理、连接器、ML、watcher 以及通过官方 Elasticsearch JS 客户端和原始 REST 访问实现的通用 API 覆盖。 | 资源 | 链接 | |---|---| | npm | [`@false00/pi-elasticsearch`](https://www.npmjs.com/package/@false00/pi-elasticsearch) | | GitHub | [github.com/false00/pi-elasticsearch](https://github.com/false00/pi-elasticsearch) | | License | [MIT](LICENSE) | | Changelog | [CHANGELOG.md](CHANGELOG.md) | | 安全策略 | [SECURITY.md](SECURITY.md) | | 兼容性说明 | [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) | | 身份验证指南 | [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) | | 覆盖范围图 | [docs/COVERAGE_MAP.md](docs/COVERAGE_MAP.md) | | 示例 | [docs/EXAMPLES.md](docs/EXAMPLES.md) | | 故障排除 | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | | 贡献指南 | [CONTRIBUTING.md](CONTRIBUTING.md) | ## 为什么选择此 package 此 package 专为希望让 Pi 操作真实 Elasticsearch 集群，而无需每次都手动编写 REST 调用的用户而设计。 它的核心重点在于： - **广泛的日常覆盖** — 142 个工具，覆盖常见的 Elasticsearch 工作流 - **混合覆盖策略** — 为常见工作提供专用工具，并为长尾需求提供两个通用出口 - **对 Pi 友好的首次运行行为** — 扩展在全新安装时仍会加载，并自动创建 `~/.config/pi-elasticsearch/.env` - **结构化的错误处理** — 工具失败时会作为带有类别和指导的真实工具错误抛回给 Pi - **运维诚实的文档** — 覆盖范围声明与官方 OpenAPI 审计脚本挂钩 - **Dist 优先的 package 卫生** — 提交运行时代码、文档、测试、changelog、安全策略和 package 元数据 ## 工具覆盖范围 | 领域 | 工具数量 | |---|---:| | 核心 | 3 | | 文档 | 7 | | 搜索 + 批量 + 按任务查询 | 17 | | 日志调查 | 3 | | 索引 + 别名 + 模板 | 20 | | 数据流 | 5 | | CAT | 6 | | 集群 | 7 | | 节点 | 4 | | 采集 | 4 | | 安全 | 10 | | 快照 | 8 | | ILM + SLM | 8 | | 任务 | 3 | | 异步搜索 | 4 | | SQL + ESQL | 4 | | 转换 | 5 | | 推理 | 6 | | 连接器 | 5 | | ML | 6 | | Watcher | 4 | | 通用 REST 覆盖 | 1 | | 通用官方客户端覆盖 + 辅助工具 | 2 | | **总计** | **142** | ### 官方 API 覆盖审计 基于以下官方 Elasticsearch 规范 OpenAPI 文档进行审计： - `https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/openapi/elasticsearch-openapi.json` **2026-06-17** 审计的 API 表面暴露了： - **575 个路由** - **833 个路由/方法组合** - 观察到的方法：**GET, POST, PUT, DELETE, HEAD** 此 package 通过专用的 `elasticsearch_*` 工具覆盖常见工作流，并通过以下方式覆盖官方表面的其余部分： - `elasticsearch_client_call` — 对任何可调用的官方 `@elastic/elasticsearch` 客户端方法的通用访问 - `elasticsearch_api_call` — 针对任何 Elasticsearch API 路径的通用原始 REST 访问 有关详细信息，请参阅 [docs/API_COVERAGE_AUDIT.md](docs/API_COVERAGE_AUDIT.md)。 ## 设计理念 此 package 有意作为 Pi 的一个**薄但实用的 Elasticsearch 封装**。 这意味着： - 为常见的运维工作流提供专用工具 - 复杂的请求体通常接受 JSON 字符串，而不是试图在每个工具 schema 中对每个字段进行建模 - 官方 JS 客户端和原始 REST 辅助工具仍然可用，因此其实用性不完全依赖于数百个超窄的封装器 - 倾向于可预测的行为和可维护性，而不是通过自定义抽象层隐藏每一个 Elasticsearch 细节 ## 稳定性保证 当前保证： - 发布的工具名称一旦发布即被视为稳定 - 破坏性操作在工具命名和文档中均明确说明 - 扩展将继续延迟加载配置，因此全新安装不会在扩展加载时失败 - `elasticsearch_client_call` 和 `elasticsearch_api_call` 是实现长尾 API 覆盖的兼容层 ## 安装 作为 package 安装到 Pi 中： ``` pi install npm:@false00/pi-elasticsearch ``` 在不更改设置的情况下将其用于单次运行： ``` pi -e npm:@false00/pi-elasticsearch ``` 从此仓库进行本地开发： ``` pi -e . ``` ## 快速开始 创建或更新 `~/.config/pi-elasticsearch/.env`： ``` ELASTICSEARCH_URL=https://localhost:9200 ELASTICSEARCH_API_KEY= # 或 ELASTICSEARCH_USERNAME=elastic # 和 ELASTICSEARCH_PASSWORD=... ``` 然后用纯英语要求 Pi 操作 Elasticsearch： ``` Show cluster health Search logs-* for error events in the last hour Show the top services in logs-* for timeout errors today Build a 5 minute timeline of error logs for checkout-service in the last 24 hours Create an index template for app-* with one shard Count documents in users where active is true List running tasks ``` Pi 会在后台调用 `elasticsearch_health`、`elasticsearch_search_logs`、`elasticsearch_logs_top_values`、`elasticsearch_logs_timeline`、`elasticsearch_put_index_template`、`elasticsearch_count` 和 `elasticsearch_list_tasks` 等工具。 ## 顶级任务与示例提示词 用户通常要求 Pi 使用此 package 执行的操作： ``` Get cluster info Create an index named products Index a document into products with id 1 Search products for documents matching laptop Investigate logs-* for 500 errors in the last 30 minutes Show the top hosts for error logs in auth-service today Build a 15 minute timeline for payment-service error logs over the last 24 hours Update index settings for logs-* to set refresh_interval to 30s Create a snapshot repository Run an ingest pipeline simulation List nodes and their stats Create an API key Call the official client target indices.putIndexTemplate with these params Call /_cluster/health directly with the raw API tool ``` ## 选择专用工具还是通用工具 按以下顺序使用此 package： 1. 优先针对常见工作流使用**专用 `elasticsearch_*` 工具** 2. 当官方 JS 客户端支持某些尚无专用封装的操作时，使用 **`elasticsearch_client_call`** 3. 当需要直接的 REST 访问、原始字符串主体或面向路径的兜底方案时，使用 **`elasticsearch_api_call`** 这保持了日常使用的便利性，同时仍保留了广泛的官方访问能力。 ## 运维文档 如需设置帮助和示例，请参阅： - [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) - [docs/COVERAGE_MAP.md](docs/COVERAGE_MAP.md) - [docs/EXAMPLES.md](docs/EXAMPLES.md) - [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) ## 信任、安全和操作模型 这是一个**完全访问集群的 package**。与任何 Pi 扩展一样，如果允许 Pi 调用其工具，它可以执行真实的更改。 重要期望： - 破坏性操作（如删除、重新路由、生命周期更新、安全写入和快照删除）作为显式工具公开 - 原始和官方客户端出口可以访问没有专用封装的 endpoint - 工具失败会作为**正确的工具错误**抛回给 Pi，而不是虚假的成功 payload - 仓库包含可选的实时集成测试，但 CI 安全验证侧重于冒烟、运行时、package 和官方审计检查 - 并非所有高级 Elasticsearch 功能都能保证在每个集群或许可证级别中启用；对于这些情况，应如实展示工具失败 如果你正在评估此 package 以用于生产环境，请查看： - [SECURITY.md](SECURITY.md) - [AGENTS.md](AGENTS.md) - [CHANGELOG.md](CHANGELOG.md) - [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) - [tests/](tests/) 了解行为覆盖 - [docs/](docs/) 获取运维指导 ## 配置 ### 要求 - Node.js 22+ - 支持 extension 的 Pi 运行时 - 可访问的 Elasticsearch endpoint 或 Elastic Cloud 部署 ### 连接设置 创建 `~/.config/pi-elasticsearch/.env`： ``` # --- Connection --- ELASTICSEARCH_URL=https://localhost:9200 # ELASTICSEARCH_CLOUD_ID=deployment-name:BASE64... ELASTICSEARCH_VERIFY_TLS=true # --- Authentication --- ELASTICSEARCH_API_KEY= # ELASTICSEARCH_API_KEY_ID= # ELASTICSEARCH_API_KEY_SECRET= # ELASTICSEARCH_BEARER_TOKEN= # ELASTICSEARCH_USERNAME=elastic # ELASTICSEARCH_PASSWORD= # --- TLS --- # ELASTICSEARCH_CA_CERT_PATH=/path/to/http_ca.crt # ELASTICSEARCH_CA_FINGERPRINT=AA:BB:CC:DD:... # --- Timeouts --- ELASTICSEARCH_REQUEST_TIMEOUT_MS=30000 ELASTICSEARCH_TOOL_TIMEOUT_MS=30000 # --- 可选 transport behavior --- ELASTICSEARCH_SNIFF_ON_START=false ELASTICSEARCH_SNIFF_ON_CONNECTION_FAULT=false # ELASTICSEARCH_SNIFF_INTERVAL_MS=60000 ``` `~/.config/pi-elasticsearch/.env` 中的值优先于环境变量。 ### 配置优先级 1. `~/.config/pi-elasticsearch/.env` 2. 直接嵌入客户端时的构造函数选项 3. 环境变量 4. 内置默认值 ### 身份验证模式 支持的验证模式： - 通过 `ELASTICSEARCH_API_KEY` 提供 API key - 通过 `ELASTICSEARCH_API_KEY_ID` + `ELASTICSEARCH_API_KEY_SECRET` 提供 API key 对象 - 通过 `ELASTICSEARCH_BEARER_TOKEN` 提供 bearer token - 通过 `ELASTICSEARCH_USERNAME` + `ELASTICSEARCH_PASSWORD` 提供用户名/密码 有关更多详细信息，请参阅 [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md)。 ## 运行时行为 ### 输出模型 - 专用工具返回可供 Pi 使用的 **JSON 文本** - 长时间运行的工具可能会通过 `onUpdate(...)` 发出**进度更新** - 复杂的请求体通常作为 JSON 字符串接受，并在工具实现内部进行解析 ### 错误模型 工具失败会作为正确的工具错误抛回给 Pi。错误消息体是带有以下字段的 JSON： - `error` - `category` - `guidance` - `retryable` - `endpoint` - `method` - `target` - `httpStatus` 标准类别： - `configuration` - `validation` - `authentication` - `authorization` - `not_found` - `conflict` - `rate_limit` - `timeout` - `network` - `server_error` - `unknown` ## 工具目录 此 package 将工具分组到 `dist/tools/` 下的以下文件中： - `core.js` - `documents.js` - `search.js` - `logs.js` - `indices.js` - `data-streams.js` - `cat.js` - `cluster.js` - `nodes.js` - `ingest.js` - `security.js` - `snapshot.js` - `lifecycle.js` - `tasks.js` - `async-search.js` - `sql.js` - `transforms.js` - `inference.js` - `connectors.js` - `ml.js` - `watcher.js` - `raw.js` - `client-call.js` 有关专用表面的实用映射，请参阅 [docs/COVERAGE_MAP.md](docs/COVERAGE_MAP.md)。 ## 仓库布局 ``` dist/ Runtime extension code committed directly to the repo index.js Pi extension entrypoint elasticsearch-client.js Official client wrapper and transport helpers tool-runtime.js Shared tool execution helpers tools/ Domain tool definitions docs/ Coverage, auth, examples, compatibility, troubleshooting scripts/ Official API audit helper tests/ Smoke, runtime, package, and optional live suites .github/ CI workflow and repository automation README.md User-facing package documentation AGENTS.md Agent/maintainer guidance CONTRIBUTING.md Contributor workflow SECURITY.md Security and disclosure policy CHANGELOG.md Release history ``` ## 兼容性 此仓库基于以下设计： - Node.js `>=22` - `@elastic/elasticsearch` `9.x` - 通过 `pi.extensions` 加载 Pi package 有关说明和注意事项，请参阅 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)。 ## 开发 ``` npm install npm test npm run test:smoke npm run test:runtime npm run test:package npm run audit:official-api npm pack --dry-run ``` 可选的实时测试套件需要： ``` ELASTICSEARCH_LIVE_TESTS=1 npm run test:auth ``` 以及 [CONTRIBUTING.md](CONTRIBUTING.md) 中列出的其他 `test:*` 实时命令。 ## 发布 ``` npm test npm pack --dry-run npm publish --ignore-scripts ``` 版本控制和发布规范说明位于 [AGENTS.md](AGENTS.md) 中。 ## 支持与反馈 报告问题时，请包含： - package 版本 - Pi 版本 - Node.js 版本 - Elasticsearch 版本 - 工具名称 - 身份验证模式 - 相关的错误消息 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AI智能体插件, DevOps工具, Elasticsearch, MITM代理, 搜索与日志分析, 数据库自动化, 自定义脚本