guhanfei-ai/dsh-searchops

dsh-searchops

面向 DeepSeek Harness 的 Agent 原生搜索、日志调查与集群运维。

OpenSearch 优先。设计上保持提供商中立。

“为什么 payment-api 返回 HTTP 500？”

DeepSeek Harness
↓
dsh-searchops
↓
OpenSearch
↓
错误
模式
Trace ID
上下文
证据
↓
Agent 推理

项目状态：pre-1.0（v0.1.0）。 每个工具都严格只读——该插件只进行搜索、观察和调查；它从不写入、删除或更改集群状态。安全边界（凭据隔离、有界响应、超时、禁用重定向、不可信数据处理）已由自动化测试覆盖，但该插件尚未针对所有 OpenSearch 发行版和版本完成认证。

为什么需要 SearchOps

将 AI agent 直接指向原始的 POST /_search 端点会让它淹没在数据中。单个日志索引可能包含数十亿条文档；一次不小心的查询就会拉回数 GB 数据；满屏 900 条几乎相同的 Connection refused 行会消耗 token，却无法告诉模型任何它无法从这句话中学到的东西：“Connection refused——842 次，首次出现在 10:02，最后一次在 10:14”。

dsh-searchops 不是 OpenSearch API 封装。它是面向搜索和日志系统的 Agent 原生证据获取层。该插件负责确定性的、token 开销高昂的工作——限界、分组、指纹识别、关联——并向 agent 交付一个紧凑、结构化的证据包。Agent 负责只有它才能完成的事：推理原因。

SearchOps = 确定性证据获取
LLM       = 推理

核心能力不是“AI 可以查询 OpenSearch”——而是“AI 可以从庞大的搜索/日志系统中高效获取结构化证据，而不会淹没在原始数据中。”

功能

- 九个只读工具，位于提供商中立的 searchops_ 命名空间下——没有 opensearch_ 品牌标识，并且刻意不提供通用的 searchops_http 逃生通道。
- searchops_investigate——核心能力。一次有界调用会运行固定的证据流水线（解析 schema → 查找错误 → 分组为重复出现的指纹 → 选取代表性事件 → 提取 trace id → 关联上下文 → 建议后续查询），并返回结构化证据包。
- 确定性日志指纹识别——将 Connection refused to 10.1.2.3:6379 和 Connection refused to 10.1.2.4:6379 归并为一个带计数的模式，无需 ML，也不会过于激进（有意义的词、短数字和 HTTP 状态码会保留下来）。
- 可配置字段配置与自动检测——从不硬编码单一日志 schema。可按来源绑定 timestampField/messageField/serviceField/levelField/traceIdField，或让插件从映射中检测它们并回退到约定。
- 多个命名来源——prod、staging、local；每个来源都有自己的 URL、认证模式、凭据引用和字段配置。每个工具都接受一个可选的
source 参数。
- 真正的提供者抽象 —— 核心使用 SearchSource /
SearchQuery / SearchResult / SearchProvider 这套语言；OpenSearch 只是其背后的一个适配器。Elasticsearch 是一个有文档记录的扩展点，而不是伪造的。
- 严格的安全边界 —— 凭据永远不会进入模型上下文、工具结果、日志或错误文本；重定向被禁用，因此 Authorization 头永远不会被跨源转发；每个响应都受大小和时间限制；所有返回的内容都被视为不受信任的数据。
- 构造上受限 —— 每个列表、查询和调查都会披露截断情况（returned 与 total），而不是静默丢弃行。

架构

DeepSeek Harness
│
SearchOps（本插件）
│
┌───────────┴───────────┐
│                       │
高层工具                  原始查询层
│                       │
logs / investigate              query
aggregate / context               │
│                       │
└───────────┬───────────┘
│
领域引擎（有界、提供者中立）
│
SearchProvider API
│
┌────────────────┴────────────────┐
│                                 │
OpenSearch 适配器              Elasticsearch
(v0.1)                        (future)
│
已认证、有界的 HTTP 客户端
(timeouts · no redirects · byte caps · redaction)

从组合根向内看，各层如下：

| 层 | 文件 | 职责 |
| --- | --- | --- |
| 插件入口 | index.js | 配置 schema、apply()、系统提示词指导、工具注册、internals |
| 工具 | lib/tools/.js | 轻量的 searchops_ 工具定义：参数、呈现、渲染 |
| 领域引擎 | lib/logs.js、lib/aggregate.js、lib/context.js、lib/investigate.js、lib/search.js、lib/patterns.js | 有界、提供者中立的搜索/日志/分析/调查逻辑 |
| 运行时 | lib/runtime.js | 多源解析以及已认证、有界的 HTTP 客户端 |
| 提供者 | lib/providers/index.js、lib/providers/opensearch.js | SearchProvider 注册表和 OpenSearch 适配器 |
| 配置与字段 | lib/config.js、lib/fields.js、lib/time.js、lib/dsl.js | 源/配置解析、字段自动检测、时间范围、查询 DSL 构建器 |
| 原语 | lib/constants.js、lib/util.js、lib/budget.js、lib/failures.js、lib/render.js | 安全边界、清理、截断预算、错误模型、呈现 |

核心从不包含 opensearch.xxx 调用；只有适配器了解 OpenSearch REST API。参见 docs/ARCHITECTURE.md。

快速开始

要求

| 组件 | 支持的基线 |
| --- | --- |
| Node.js | 20.11 或更新版本 |
| DeepSeek Harness | 0.1.0-rc.6 至 0.1.5 预发布版本 |
| 搜索后端 | OpenSearch 1.x / 2.x（REST API） |

没有构建步骤：该插件是纯 ESM JavaScript。

安装

已发布的标签（推荐）
dsh plugin --profile  add github:guhanfei-ai/dsh-searchops#v0.1.0

本地开发
npm ci
dsh plugin --profile  add link:/absolute/path/to/dsh-searchops

安装后重启所选的 DSH 配置文件。

配置一个数据源

在 设置 → 插件 → SearchOps 中，添加一个数据源。机密信息绝不在此处输入——只输入凭据引用，其值存放在 DSH 凭据存储中：

{
"sources": [
{
"name": "prod",
"provider": "opensearch",
"url": "https://search-prod.example.com:9200",
"auth": "basic",
"username": "searchops-reader"
}
],
"defaultSource": "prod",
"allowInsecureHttp": false
}

将密码存储在由数据源 id 派生的引用下（SEARCHOPS_PASSWORD_prod）。然后向智能体提问：

Is the prod search cluster healthy?
Show me the last hour of payment-api errors.
Investigate why payment-api is returning 500s.

配置

插件配置由 schema 校验；未知或格式错误的输入会被拒绝，并给出清晰、不含机密信息的消息。

| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| sources | array | [] | 已配置的搜索数据源（见下文） |
| profiles | array | [] | 用于非标准 schema 的可选字段配置文件 |
| defaultSource | string | "" | 当工具调用省略 source 时使用的数据源；当恰好只有一个数据源时，它会自动成为默认值 |
| allowInsecureHttp | boolean | false | 允许对非回环主机使用纯 HTTP。默认关闭 |

数据源对象

| 字段 | 默认值 | 含义 |
| --- | --- | --- |
| id | （系统） | 只读、系统生成的唯一 id。凭据引用由它派生 |
| name | — | 智能体用于选择数据源的唯一句柄（任意语言） |
| provider | opensearch | v0.1 中仅支持 opensearch；elasticsearch 是路线图项目 |
| auth | basic | none、basic 或 bearer |
| url | — | 基础 URL，例如 https://search.example.com:9200。不得包含凭据、查询字符串或片段 |
| username | "" | 用于基本认证的可选非机密用户名 |
| usernameRef | （派生） | 基本认证用户名的凭据引用 |
| passwordRef | （派生） | 基本认证密码的凭据引用 |
| tokenRef | （派生） | 持有者令牌的凭据引用 |
| profile | "" | 绑定到此数据源的字段配置文件名称；空 = 自动检测 |

解析器也接受对象映射形式（{"sources": {"prod": {...}}}）以方便使用；上面的数组形式是设置 UI 所编辑的形式。

多个数据源

配置任意数量的数据源（最多 50 个），并在每次调用时指定一个：

{
"sources": [
{ "name": "prod",    "url": "https://search-prod.example.com:9200",    "auth": "basic",  "username": "searchops-reader" },
{ "name": "staging", "url": "https://search-staging.example.com:9200", "auth": "bearer" },
{ "name": "local",   "url": "http://localhost:9200",                   "auth": "none" }
],
"defaultSource": "prod"
}

每个工具都接受一个可选的 source 参数（即源名称）。省略它则使用默认值。请先调用 searchops_sources 来发现有效的名称、提供方、经过净化的 URL、认证模式、绑定的配置文件以及凭据是否已配置（绝不会返回凭据值）。

每个源都保留自己的 URL、凭据和字段配置文件；对 staging 的请求绝不会触碰 prod 的凭据。http://localhost（回环地址）无需 allowInsecureHttp 即可使用；任何其他纯 HTTP 主机都会被拒绝，除非操作员明确选择允许。

字段配置文件

日志领域最大的痛点在于模式并不统一。一个索引使用 @timestamp / message / service.name；另一个使用 ts / msg / app。dsh-searchops 从不硬编码单一模式。每个角色的解析顺序如下：

1. 配置文件 — 源所绑定配置文件中指定的字段优先。
2. 自动检测 — 否则插件会查看索引映射（或样本），并选择第一个存在的已知候选字段。
3. 约定 — 否则使用最常见的名称，以便查询仍然可用。

{
"profiles": [
{
"name": "ecs",
"timestampField": "@timestamp",
"messageField": "message",
"serviceField": "service.name",
"levelField": "log.level",
"traceIdField": "trace.id"
},
{
"name": "custom",
"timestampField": "ts",
"messageField": "msg",
"serviceField": "app",
"levelField": "severity",
"traceIdField": "request_id"
}
]
}

使用 "profile": "ecs" 将配置文件绑定到某个源。将其留空则自动检测。每个 logs/context/investigate 结果都会报告其实际使用的字段，并标记哪些角色是猜测的，这样代理就能在检测结果看起来有误时告知你。

每个角色的检测候选字段包括：时间戳（@timestamp、timestamp、time、created_at、……）、消息（message、msg、log、text、……）、服务（service.name、service、app、application、……）、级别（log.level、level、severity、……）、跟踪 ID（trace.id、traceId、request.id、correlation.id、……）。

工具

全部九个工具都是只读的、有界的，并返回不受信任的数据。它们都不需要审批，因为它们都无法修改任何内容。

| 工具 | 用途 |
| --- | --- |
| searchops_sources | 列出已配置的源（名称、提供方、经过净化的 URL、认证、配置文件、凭据是否已配置、默认源）。绝不返回机密值 |
| searchops_status | 可达性 + 集群健康：发行版、版本、集群名称、状态、节点数和分片数 |
| searchops_indices | 列出索引，可选按模式筛选；分页，包含文档数和存储大小 |
| searchops_mapping | 检查索引的字段（扁平化路径 + 类型），或使用有界的原始映射模式 |
| searchops_query | 为高级用户提供有界的原始 OpenSearch/Elasticsearch DSL 查询 |
| searchops_logs | 按时间范围、服务、级别和自由文本进行语义日志搜索——无需了解字段名称 |
| searchops_aggregate | 在索引上进行分组/计数/指标统计，和/或日期直方图，而无需拉取文档 |
| searchops_context | 获取某个事件（按时间戳）周围的日志行，或共享同一 trace id 的所有事件 |
| searchops_investigate | 固定的、有界的调查，返回结构化的证据包 |

边界一览

| 关注点 | 默认值 | 硬性上限 |
| --- | --- | --- |
| searchops_query 大小 | 20 | 200（绝对上限 500） |
| 结果偏移量（from） | 0 | 10 000（拒绝深度分页） |
| 日志行数 | 50 | 500 |
| 聚合桶数 | 20 | 200 |
| 每侧上下文行数 | 20 | 200 |
| 每侧上下文窗口 | 300 秒 | 3 600 秒 |
| 每次调用时间窗口 | — | 31 天 |
| 响应体 | — | 4 MiB（流式传输，提前放弃） |
| 每请求超时 | 15 秒 | — |
| 调查扫描文档数 | — | 500 |

示例

状态

searchops_status { "source": "prod" }
→ source="prod" url="https://search-prod.example.com:9200" reachable=yes
cluster="prod-cluster" distribution=opensearch version=2.11.0 node="node-1"
health=green nodes=3 dataNodes=2 shards: active=20 activePrimary=10 unassigned=0 …

语义日志

searchops_logs { "index": "logs-", "service": "payment-api", "level": "error", "from": "now-15m" }
→ logs on "logs-" range=now-15m..now matched=137 returned=50 took=42ms
fields: timestamp=@timestamp message=message service=service.name level=log.level trace=trace.id
2024-01-15T10:14:02Z ERROR [payment-api] Connection refused to db-1 trace=t1 id=…
…

聚合

searchops_aggregate { "index": "logs-", "groupBy": "service", "from": "now-15m" }
→ aggregate on "logs-" range=now-15m..now matched=947 took=18ms
groups by "service.name":
payment-api count=732
checkout    count=211
auth        count=4

原始查询（高级用户）

searchops_query {
"index": "logs-",
"query": { "bool": { "filter": [ { "term": { "http.response.status_code": 500 } } ] } },
"size": 20
}

调查工作流

searchops_investigate 是处理事故的推荐入口。这正是 SearchOps 超越 es_query_logs 的地方：

用户：
调查 prod 中过去 15 分钟内 payment-api 的错误。

Agent：
searchops_investigate { "source": "prod", "index": "logs-",
"service": "payment-api", "from": "now-15m" }

SearchOps（确定性、有界、只读）：
- 解析 logs-* 模式（映射 → 字段画像）
- 过滤时间窗口和服务，仅限错误级别
- 将错误文档按重复指纹分组，并附带计数 + 首次/最后出现时间
- 为每个模式挑选一个代表性样本
- 提取 trace/request id
- 为排名靠前的 trace 拉取关联上下文
- 输出确定性的下一步查询建议

对 "logs-" 的调查（now-15m..now）service="payment-api"
scanned=137 doc(s); matched=137; distinct patterns=3; error-level filter=on

重复模式（按频率从高到低）
1. [112x] Connection refused to :
first=2024-01-15T10:02:11Z last=2024-01-15T10:14:58Z services=payment-api
sample: Connection refused to 10.1.2.3:6379 (id=…)
traces: t1, t2, t3, t4, t5
2. [21x] Redis timeout after …
3. [4x] NullPointer …

关联 trace（同一请求中还发生了什么）
trace=t1 events=6 services=payment-api,cache,db
…

建议的下一步（确定性——由你判断原因）
- 在 logs- 上执行 searchops_logs，query="Connection refused"，以读取原始日志行…
- 在 logs-* 上执行 searchops_context，traceId="t1"，以查看完整请求路径…
- 在 logs-* 上执行 searchops_aggregate，groupBy="service.name" …
- 在 logs-* 上执行 searchops_aggregate，interval=5m，以查看错误何时开始…

仅为证据——该插件不会推断根本原因。

Agent：
使用证据包来推理可能的原因
（例如缓存层在 10:02 拒绝连接，并蔓延到 payment-api）。

该插件收集并组织证据；它刻意不判定根本原因。那项推理是模型的职责。

安全

dsh-searchops 在设计上是只读的，并会防御每一个请求。完整细节见
docs/SECURITY.md。

- 只读。 没有任何工具会写入、删除或修改集群状态。破坏性操作不在 v0.1 的范围内，当它们到来时将需要 dsh-human-intent 授权。
- 凭据隔离。 密钥在请求时从 DSH 凭据存储中解析，并直接进入 Authorization 头。它们绝不会出现在配置、工具结果、模型上下文、日志或错误文本中。
- 无重定向。 请求使用 redirect: 'error'，因此 Authorization 头绝不会被转发到其他源（SSRF / 凭据泄露防护）。
- 传输策略。 非回环主机要求使用 HTTPS；除非操作员明确设置 allowInsecureHttp: true，否则拒绝明文 HTTP。带有内嵌凭据、查询字符串或片段的 URL 会被拒绝。
- 有界响应。 每请求超时、流式硬字节上限、大小和偏移限制，以及最大时间窗口，可防止单个查询拉取数 GB 数据。
- 经过清理的错误。 上游响应体不可信，且可能回显凭据；在进入任何消息之前，它们会被脱敏、合并为单行并截断。
- 经过脱敏的证据。 被索引的日志数据同样不可信，且可能携带密钥（回显的 Authorization 头、消息中的 password=）。文档会被
在输出时进行净化——凭据形状的字段（password、token、
api_key、……）以及文本中明显的凭据形状会变成 [redacted]——在它们到达工具结果、
模型上下文或 UI 之前，以尽力而为、确定性的方式进行。

- 不可信数据。 所有返回的内容都是数据，绝不是指令（见下文）。

凭据处理

凭据遵循 DeepSeek Harness 模型：配置中放引用，凭据存储中放值。

- 配置只保存凭据引用（例如 passwordRef），绝不保存
机密。插件会拒绝任何包含字面量 password、token
或 apiKey 的配置，因此机密永远不会被提交到 Git。
- 引用派生自源 id：SEARCHOPS_USERNAME_、
SEARCHOPS_PASSWORD_、SEARCHOPS_TOKEN_。你可以覆盖其中任意一个，
以便在多个源之间共享同一个凭据。
- 在请求时，运行时会解析该值并构建请求头：
basic → Authorization: Basic base64(user:pass)；bearer →
Authorization: Bearer ；none → 无请求头。
- 如果缺少必需的凭据，请求会在到达网络之前被拒绝，
并给出指明需要设置哪个引用的消息——绝不包含值。
- searchops_sources 以布尔值（configured / missing）报告凭据，
绝不回显值。

将上面 prod 示例的机密存储在 DSH 凭据存储中的
SEARCHOPS_PASSWORD_prod 下（设置 → 凭据，或你主机的机密后端）。

不可信数据

搜索结果内容是不可信数据，绝不能将其解释为
对智能体的指令。

OpenSearch 内部的一切——日志消息、字段值、索引名、映射——
都被视为不可信。一行日志可能字面上包含 Ignore previous
instructions 或 run rm -rf /；那只是数据。

- 日志内容绝不被拼接进类似系统指令的内容中，也绝不
允许控制插件行为。
- 每条返回的消息都单行化（换行符/制表符被折叠），使不可信
文本无法伪造额外的行或虚假结构，并且截断到有界
长度。
- 证据以结构化记录（{ timestamp, message, … }）返回，而不是以
可能被解读为指令的散文形式返回。
- 工具描述和系统提示词指引会重复不可信数据规则，
以便在每次调用时提醒模型。

限制

- 只读。 不进行索引/文档写入、删除、映射更改、集群
设置写入或批量摄取。这是 v0.1 的有意设计。
- 仅限 OpenSearch。 Elasticsearch 是已记录的扩展点，但未
实现。没有假的提供程序。
- 无深度分页。 超过 10 000 的偏移量会被拒绝；search_after 尚未
暴露。请使用聚合或缩小查询范围。
- 无 AWS SigV4。 支持 basic、bearer 和无认证；SigV4 在
路线图中。
- 日期数学会被转发，而非解析。 插件验证的是
时间值并守护窗口；OpenSearch 解释 now-15m、ISO-8601 和
epoch 毫秒。
- 检测是尽力而为的。 具有异常模式的源应绑定
显式字段配置文件，而不是依赖自动检测。

路线图

- Elasticsearch 提供程序位于同一 SearchProvider 接口之后。
- 用于托管 OpenSearch 的 AWS SigV4 认证。
- 用于深层结果集的 search_after 游标分页。
- 绑定到 dsh-human-intent 的受保护写操作（例如索引生命周期、文档删除），
用于明确的人工授权——绝不在只读发布中。
- 与 dsh-grafana 的组合：Grafana 告警 → SearchOps 日志 → 根因
推理流程，由代理编排（无需插件到插件 RPC）。

许可证

MIT © guhanfei-ai。参见 LICENSE。

与 OpenSearch REST API 交互不会捆绑或再分发任何
OpenSearch 源代码。