概念

本页按依赖顺序介绍 Ongrid 用到的名词。如果你跑过快速开始，这些东西的实物你已经见过了；这里只是给它们贴上名字。

Edge

一个 edge = 一个跑着的 ongrid-edge 进程——每台主机一个。它是注册、遥测和远控的单位。

每个 edge 都有：

服务端生成的 access key（半公开，标识 edge）和 secret key（只显示一次，用来鉴权隧道），
一条到 frontier broker 端口 40012 的长连外联 TCP，
一队被监管的 plugin 子进程（promtail、node_exporter、process_exporter、otelcol-contrib），
几秒一次的心跳——停了之后，超过 ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD（默认 90s）就标记 offline。

Edge 可以用整型 edge_id（URL 和 Agent 工具调用里用）或者 name（UI 和 find_topology_node 里用）寻址。你可以 list_edges 列出所有 edge，用 bash 加 edge_id=N 在某台跑命令，或用 query_promql 配 host label 把 PromQL 查询限定到一台。

重要一点：edge 默认只读。Agent 的主机侧技能都是巡检类（bash、host_probe_*、query_processes、query_logs_tail、host_read_file）——它们不写。写动作走 WebShell 流程，带审计日志。

具体部署路径参见 edge 安装和平台 / linux-edge。

Device

device 比 edge 软一点。Edge 一对一对应一个 ongrid-edge 进程；device 则是 Ongrid 已知、参与拓扑的任何东西——包括服务、虚拟主机、k8s pod，以及通过 SD 或手工导入发现的外部端点。

目前 UI 通过拓扑视图隐式呈现 device。Device 是拓扑图里的一个节点；edge、服务、被发现的外部系统都是节点。expand_topology 和 find_topology_node 技能就在 device 上跑——爆炸半径推理依赖这张图。

TIP

如果你目前只有 edge，拓扑图就是单层主机节点。等 discover_services 这种技能和 k8s SD 集成给图加料后，你会看到主机上方出现服务节点、旁边出现外部端点。

Alert rule

alert rule 是声明式规格：当某个条件在某条遥测流上成立时触发告警事件。

Ongrid 的规则模型是二维的：每条规则有一个 kind（评估哪种数据类型）和一个 scope（在哪评估）。

内置的 14 种 kind，按数据面分组：

数据面	Kind
主机指标	`host_cpu`、`host_mem`、`host_disk`、`host_load`、`edge_offline`、`prom_ingest_fail`
指标/PromQL	`promql_threshold`、`promql_burn_rate`、`promql_absence`
日志	`log_match`、`log_volume`
链路	`trace_latency`、`trace_error_rate`
组合	`composite_and`（上述任意，AND）

规则携带：

用该 kind 原生查询语言写的 condition，
threshold + for 时长（条件成立多久才触发），
severity（critical / warning / info），
routing —— 哪些通道收通知，可选冷却。

6 条内置主机规则（host_cpu、host_mem、host_disk、host_load、edge_offline、prom_ingest_fail）从 ONGRID_ALERT_* 环境变量取合理默认值，UI 上可以开关。自定义规则存 MySQL，可以自由编辑。

参见告警能力；规则 schema 文档在 Reference 边栏的 Alert rule schema 下。

Incident

incident 是把属于同一个运维故事的告警事件聚合到一起的更高阶概念。告警条件每次成立都会触发一条 alert event，但 incident 只创建一次，相关 alert 来了就更新。

Incident 是以下事项的单位：

investigation —— 一个 incident 可以有一个或多个 investigation。
paging —— 通道路由发生在 incident 创建时，不是每条 alert 都走一次。
timeline —— Incident 详情页是同一个故事下所有 alert 事件、Agent 动作、运维人员备注的时序记录。
closure —— Incident 在 open → investigating → mitigated → resolved（或 false_positive）之间流转。状态变更进审计日志。

聚合逻辑目前刻意简单：按 {rule_id, edge_id} 元组，1 小时活动窗口。Roadmap 是按规则可配（group_by）。

Investigation

investigation 是挂在 incident 上的一次结构化 Agent 运行。输出是一份 Markdown investigation 报告——按可能性排序的根因列表 + 证据。

典型 investigation 会走五个子 Agent：

incident-investigator（coordinator）—— 把 incident 拆成假设。
sre specialist —— 检查 SLO burn、近期发布、告警关联。
compute / disk / network specialist —— 在受影响 edge 上做主机层探测。
ops specialist —— 查知识库、匹配 runbook。
reviewer（critic 环路）—— 重读草稿报告，签字前补齐缺失证据。

每一步都进 UI 里的推理时间线——每次工具调用、每个模型 token、每次子 Agent 派发。可审计是重点。

你也可以从任意 incident 或聊天里手动启动 investigation（"investigate the order-service drop at 14:02"）。输出走同一个地方：挂在 incident 上的 investigation 报告。

参见RCA 能力；跑 investigation 的 persona 文档在 Agents 边栏的 Incident investigator 下。

Channel

channel 是配好的通知出口。"通道"覆盖两种略不同的形态：

Webhook 通道 —— Slack incoming webhook、飞书 webhook、钉钉 webhook、企业微信群机器人、通用 webhook。这些是单向——Ongrid 推一张卡片就完了。
IM 通道 —— Telegram bot、飞书 app、钉钉 app、企业微信 app、Slack app。这些是双向——同一个通道既送告警，又让用户回消息、问 Agent、触发 investigation。

每个 channel 都有：

name（自由文本）、type（slack / feishu / dingtalk / wecom / webhook / telegram）、endpoint 材料（URL + secret，或 app token + chat ID，或 bot token + allow-from 列表……）。
scope —— 这个通道发出的通知哪个 org / 哪些角色能看见。再加一个可选的 allow_from 发送者白名单（Telegram 专属），防止陌生人跟你的 bot 聊天。
default locale —— Agent 在这个通道回复用什么语言，跟 UI locale 独立。

通道是一等公民：告警规则按名字引用它们，Agent 可以主动给它们发消息，一个通道挂多条规则也不用重复贴 webhook URL。

参见通道概览。

IM 通道（双向）

"通道"的一个子类型，单独拎出来讲。IM 通道把聊天界面（Telegram、飞书、钉钉、企业微信、Slack）变成一个完整的 Agent 接口。

双向具体意味着：

Agent 能发 —— 告警、investigation 报告、定时摘要。
用户能回 —— 问问题（"为什么磁盘满了？"）、命令（"/list edges"）、追问（"investigate that"）。
每条消息绑到与 Web UI 会话相同的 user_agent 和 org —— 同一套 RBAC、同一份审计日志、同一份技能注册表。
sender_allowlist（Telegram）或 app 权限门（其他几种）决定谁可以在群里跟 bot 说话。

按通道 locale 在这里很重要。用户的 UI locale 可能是英文；Telegram 群仍然可能想要中文回复；你按通道分别配。

最灵活的例子参见通道 / telegram。

Persona / agent

persona 是可配置的 Agent 身份——一份 YAML/JSON 声明：

该 Agent 偏好哪个模型（取不到时回退到站点默认），
允许使用哪些技能（技能带 scope：host、manager、org，以及 class：safe、payload_read、payload_write —— 参见 RBAC），
Agent 的 voice 体现在 system prompt，
可选的子 Agent 声明（coordinator persona 可以派生 specialist persona）。

Ongrid 开箱即用几个 persona：

coordinator —— 默认；拆解用户问题，路由给 specialist 或直接跑技能。
incident-investigator —— incident 模式下的 coordinator；走拓扑、关联信号、写报告。
sre、network、compute、disk、ops —— coordinator 调用的 specialist。
reviewer —— incident-investigator 草稿的 critic 环路。

你可以写自己的。Persona 格式文档在 Reference 边栏的 Agent persona format 下。自定义 persona 落 MySQL；下次 Agent 运行就生效。

Skill

skill 是 Agent 可调用的工具。每个 skill 声明：

name（如 query_promql、bash、expand_topology），
参数和结果的 JSON schema，
scope —— host（在某个 edge 上经隧道执行）、manager（在 manager 进程里执行）、或 org（跨 edge 的 manager 技能），
class —— safe、payload_read、payload_write。只读类不限；写类走审批。
可选的激活关键词 —— 设了之后，skill 只有在用户提问含某关键词时才进 prompt。这是 toolbag 延迟机制，防止技能注册表撑爆模型上下文窗口。

技能存在注册表里。Agent kernel（默认 graph kernel）根据 scope、RBAC 和激活关键词，解出当前回合可见的技能集合。开箱大约 30 个技能（bash、host_probe_*、query_promql、query_logs、query_traceql、expand_topology、find_topology_node、read_repo、search_knowledge、web_search ……）。

参见技能能力；manifest 格式文档在 Reference 边栏的 Skill manifest 下。自定义技能可以从 ONGRID_SKILLS_EXTERNAL_DIRS 加载。

知识库

知识库是组织文档集合，Agent 通过 search_knowledge 搜索它。文档一次性嵌入并存到 Qdrant；检索是混合的（向量 + BM25）。

来源分层：

vault —— Ongrid 自带的内置只读知识。大约 100 篇 Markdown playbook，覆盖网络诊断、Linux 内部、Prometheus / Loki / Tempo recipe、常见 incident 模式。Vault 按需从公开仓库 ongridio/vault 同步。
upload —— org 管理员上传的 Markdown、TXT、PDF、DOCX 文件。走 docextract 落到 upload 树。
manual —— 直接在 UI 编辑器里写的条目。
repo —— 整个 Git 仓库通过只读 SSH key 同步（ADR-023）。适合接你自己的 runbook 仓库。

Agent 调用 search_knowledge(query, k=N)，拿回排好序的 chunk 及元数据。Embedding 默认由离线 ONNX 打包的 BGE 模型计算（fast-bge-small-zh-v1.5）；你也可以从 Settings 换成托管 embedder（OpenAI、Zhipu、GLM……）。

参见知识库能力。

全链路串起来

典型的运维闭环：

text

  edge ─▶ telemetry ─▶ alert rule ─▶ alert event ─▶ incident
                                                       │
                                              ┌────────┴────────┐
                                              ▼                 ▼
                                       investigation        channel
                                       (agent + skills)     (Slack / TG /
                                              │              IM …)
                                              ▼
                                       investigation
                                       report

edge 上报遥测。
alert rule 评估它，产出 alert event。
事件归组成 incident（或挂到开着的那个上）。
Incident 路由到 channel 发通知。
investigation 自动启动（或运维人员触发）；Agent 用 skill 和知识库产出报告。
persona 决定 investigation 跑的 voice + 工具集。

整条管道可观测：每一步都在 UI timeline 里，每次技能调用都在审计日志里，每个 token 消耗都在 LLM 预算面板里。

概念 ​

Edge ​

Device ​

Alert rule ​

Incident ​

Investigation ​

Channel ​

IM 通道（双向） ​

Persona / agent ​

Skill ​

知识库 ​

全链路串起来 ​

概念