逐文件还原 Ongrid 的运维大脑

三者通过 .go-arch-lint.yml 强制隔离，只能借 internal/pkg/**（业务无关共享层）和 api/ 通信。技术栈：Go（Chi router + cloudwego/eino agent 框架 + singchia/geminio 反向隧道）+ TypeScript/React SPA + MySQL/SQLite + frontier broker + Docker Compose。

设计哲学：深度数据查询和高危执行能力都下沉到 edge 和 specialist，coordinator 只做"派给谁 / 直接答 / 直接拒"的调度，并通过 cmdpolicy 沙箱 + ReviewGate 二审把"AI 误操作"的爆炸半径压到最小。边缘 agent 永远是发起方（dial-out）；manager 想调用 edge 的能力是通过 frontier broker 反向调用边缘已注册的 RPC handler，而非主动连边缘端口。

                            浏览器 SPA (web/  React+TS)              IM 平台
                          ┌──────────────────────┐      Slack / Telegram / 飞书(Lark)
                          │ /chat  /webshell      │      DingTalk / WeCom / Webhook
                          │ /topology /incidents  │              │
                          └──────────┬───────────┘              │ (webhook + 长连接 stream)
                                     │ HTTP / WebSocket / SSE     │
┌────────────────────────────────────┼─────────────────────────────┼──────────────────────────┐
│  cmd/ongrid  (manager + iam 装配)    │                             │                          │
│                                     ▼                             ▼                          │
│  ┌──────────────────────────────────────────────┐   ┌────────────────────────────────────┐ │
│  │ internal/manager/server (Chi handlers)        │   │ internal/manager/biz/imbridge       │ │
│  │  aiops/http  webshell/http  edgeauth ...       │   │  bridge → adapter → AgentSession    │ │
│  └───────────────────────┬───────────────────────┘   │  provider/{feishu,slack,telegram}   │ │
│                          ▼                            │  StreamSupervisor (长连接 reconcile)│ │
│  ┌─────────────────────────────────────────────────┐ └──────────────────┬─────────────────┘ │
│  │ chatruntime.Runtime  (eino ReAct 图引擎)         │◄───────────────────┘                   │
│  │  ┌──── COORDINATOR (persona="default") ────────┐ │                                        │
│  │  │ 受限 toolBag: query_devices / query_incidents│ │                                        │
│  │  │   get_topology / query_knowledge / search_web│ │     ┌──────────────────────────────┐  │
│  │  │   read_source/grep_source + AgentTool        │ │     │  internal/pkg/llm (router)    │  │
│  │  └──────────────┬───────────────────────────────┘ │────►│  OpenAI/Anthropic/GLM/        │  │
│  │     AgentTool.SpawnWorker (同步派活)             │ │     │  DeepSeek/Gemini/Kimi 热路由  │  │
│  │                 ▼                                 │ │     └──────────────────────────────┘  │
│  │  ┌──── SPECIALIST WORKERS (各自 persona) ───────┐│ │                                        │
│  │  │ specialist-compute / -disk / -network / -ops ││ │     ReviewGate 二审装饰器              │
│  │  │ specialist-sre / incident-investigator       ││ │     (write/destructive → spawn reviewer)│
│  │  │ 每个 worker = filterToolsForAgent 后的子 bag ││ │                                        │
│  │  └──────────────┬───────────────────────────────┘│ │                                        │
│  └─────────────────┼─────────────────────────────────┘ │                                        │
│         tools/ (BaseTool + 装饰器链)                    │                                        │
│  query_promql/logql/traceql  correlate_incident         │     数据存储                           │
│  expand_topology  host_bash  host_restart_service ...   │  MySQL/SQLite  topology graph          │
└─────────────────┬───────────────────────────────────────┴────────────────────────────────────┘
                  │ tunnel.Caller.Call(edgeID, method, body)   ▲ AcceptStream (webshell forward)
                  ▼                                            │
        ┌──────────────────────────────────────────────────────────────┐
        │  frontier broker (singchia/frontier:1.2.5)  —— 路由/鉴权中枢   │
        └──────────────────────────────┬───────────────────────────────┘
                                        ▲  edge 主动 Dial 出站 (TCP/TLS)，零入站端口
                                        │  geminio RetryEnd 自动重连
        ┌───────────────────────────────┴───────────────────────────────┐
        │  cmd/ongrid-edge (装在被管主机上)                               │
        │  tunnel.Client  →  register_edge / heartbeat / push_*          │
        │  RPC handlers:  get_host_load / get_process_list / execute_skill│
        │  cmdpolicy 沙箱(只读 binary 白名单)  webshell TCP 转发到 :22    │
        │  plugins: hostmetrics / metrics / logs / traces / procmetrics  │
        └───────────────────────────────────────────────────────────────┘
                 Prometheus  ◄── remote_write ──  Loki ◄── push ──  Tempo

buildAIOpsRuntime（main.go:2376）是整个 AIOps 装配的咽喉——它把每个依赖恰好穿过一次。Coordinator 的 coordinatorToolNames（main.go:2362）被刻意收窄成只读定位 + 知识工具，注释直言这是 "rule 1 的物理执行"：coordinator 的 toolBag 里根本没有 query_promql / host_bash 这类深度工具，所以 LLM 即使想 inline 查也调不到，只能走 AgentTool 派给 specialist。

var coordinatorToolNames = []string{
    "query_devices", "query_incidents", "get_topology", "query_knowledge",
    "search_web", "list_repo_sources", "read_source", "grep_source",
}

派活路径：coordinator 的 LLM 调 AgentTool（PascalCase，刻意对齐 claude-code 的工具名以利模型选择，见 agent_tool.go:91）。AgentTool 是 coordinator-only 工具，tools 包不能 import chatruntime（会循环），所以它通过 WorkerSpawner 窄接口调用，由 main.go 装配处把 *chatruntime.Runtime shim 成该接口。AgentTool 默认同步派活，拿到 worker 结论后强制 coordinator 收口：

w, err := t.spawner.SpawnWorker(ctx, SpawnWorkerRequest{
    AgentName: args.SubagentType,
    Prompt:    args.Prompt,
    Locale:    basetool.LocaleFromContext(ctx),  // 把 UI 语言透传给 specialist
})
// ...
res.Hint = "Specialist " + args.SubagentType + " 已经返回最终结论（见 result 字段）。" +
    "直接基于它给用户写最终答复；**不要再调用任何工具**…"

Worker 隔离（worker.go:522 runWorker）：每个 worker 跑独立 graph.Invoke，toolBag 经 filterToolsForAgent 用 persona 的白名单 + 黑名单裁剪（black wins），并强制剥离 coordinatorOnlyTools（AgentTool/SendMessage/TaskStop）——worker 不能 spawn 嵌套 worker。worker 有自己的 session id（worker-<8hex>），消息历史对父不可见。

var coordinatorOnlyTools = map[string]bool{
    "AgentTool": true, "SendMessage": true, "TaskStop": true,
}
func filterToolsForAgentRole(bag, agentDef, isCoordinator, viewerOnly) []BaseTool {
    // viewer 降级：先砍掉所有 Class!=read 的工具
    // coordinator-only 工具只在 isCoordinator=true 时保留
    // 否则按 persona 白名单过滤，再减黑名单（支持 *_skill 通配）
}

Agent loop（graph/react.go）：外层包一个 eino react.Agent，关键修正是 MaxStep = MaxIterations*2 + 2——因为 eino 把每个节点 visit 都算一步，一轮 ReAct = ChatModel + ToolsNode = 2 步，不 ×2 会让 LLM 在 30 轮上限时只跑到 ~15 轮就 ErrExceededMaxSteps。反漂移机制：每轮在 user 消息前注入独立的 <system-reminder> user-role 消息（graph/react.go:271 buildSystemReminder），内容 = 硬编码基线规则 + persona 的 critical_reminder + runtime 动态启发式（runtime.go:863 calcDynamicHints：同工具连续失败、迭代数过高、重复调用同一 (tool,args)、"承诺但没发 tool_call" 检测）。

dial-out：首次拨号指数退避 1s→2s→…封顶 60s；连上后断线由 geminio RetryEnd 透明重连。手柄 blob Meta{AccessKey, SecretKey} 在 connect 时塞进 geminio 不透明 Meta，server 端解码后做 AuthFunc。manager 想调边缘能力时是反向 Call：tunnel.Caller.Call(edgeID, method, body) 经 broker 路由到该 edge 已注册的 handler。一个微妙坑——manager 重启会清掉 broker 路由表但 edge 的 TCP 还活着，所以 client 额外检测 broker 路由失效错误重连：

func shouldReconnect(err error) bool {
    msg := err.Error()
    return strings.Contains(msg, "not found") ||
        strings.Contains(msg, "mismatch clientID")
}

Browser SSH：架构经过一次重构——SSH 协议栈完全搬到 manager 侧，边缘退化成"一屏 TCP 转发器"。manager 用一个携带 {"target":"127.0.0.1:22"} Meta 的 stream 进 edge，edge 校验 target 在 allowlist 内后 dial 本地 sshd，双向 io.Copy：

var allowedTargets = map[string]bool{
    "127.0.0.1:22": true, "localhost:22": true,
}
// localhost narrow scope 是安全边界——否则被攻破的 manager 能把 edge 当跳板打内网

manager 侧 biz/webshell/router.go 维护 SessionID → Sink 目录，把 edge 推回的 stdout 路由到对应浏览器 WebSocket；记录 per-session 字节数、支持 admin kill、idle watchdog、per-user/per-device 并发限制。SSH 口令 SSHPass 是一次性的，Dial 后从 edge 内存抹掉，永不落盘/落日志（messages.go:84 注释）。

type correlateIncidentBundle struct {
    Incident    incidentSummary   // 规则名/severity/target/fired_at/labels
    Window      windowRange       // 以 first_fired_at 为中心 ±window/2
    MetricPanel []metricSeries    // PromQL range，top-3 series by magnitude
    LogPanel    []logEntry        // Loki: {edge_id} |~ "(?i)error|panic|oom|fatal|fail"
    TracePanel  []traceEntry      // Tempo: service.name 过滤
    Edge        *edgeSnapshot     // 当前 cpu/mem/up + 24h flap 计数
    Skipped     map[string]string // 哪个面板因何跳过（无 client/无 edge_id…）
    Truncated   map[string]int    // 100KB 上限时砍 logs→traces→metric values
}

PromQL 表达式由 metricExprFor 从规则的闭集 metric 名（cpu_pct/mem_pct/disk_used_pct/load1…）翻译，再用 wrapPerEdge 用 ... and on(edge_id) (group by (edge_id) ({edge_id="N"})) 限定到单台。每个子查询有独立短 deadline（trace/log/edge 互不阻塞），整体 60s 封顶，bundle 超 100KB 时按"先砍 logs 再砍 traces 最后砍 metric values"降级，并在 Truncated 里告知 LLM "你看的不是全貌"。

inbound 流程（HandleInbound）：去重（provider:app_id:event_id，防长轮询 replay 重复应答）→ 解析 app/thread 映射（按 (im_app_id, im_chat_id, thread_id) 一聊一 session，群里所有人共享）→ /new 等命令重置 session → 发 "✦ 思考中…" placeholder → 跑 agent + 节流编辑器渐进编辑 IM 消息。outbound 渐进编辑：newStreamEditor 把 agent SSE 的 assistant chunk 节流后不断 edit 同一条 IM 消息。

飞书验签/解密（provider/feishu/verify.go）有个反直觉点——飞书 v2 events 用的是 SHA-256 拼接而非 HMAC：

// sig = sha256(timestamp + nonce + encryptKey + body), hex
func VerifyEventSignature(timestamp, nonce, encryptKey string, body []byte, signatureHex string) error {
    h := sha256.New()
    h.Write([]byte(timestamp)); h.Write([]byte(nonce))
    h.Write([]byte(encryptKey)); h.Write(body)
    // ...
}
// DecryptEvent: AES-256-CBC，key=sha256(encrypt_key)，IV=密文前16字节，PKCS#7 去填充

长连接管理（stream_supervisor.go）：每个启用的 stream-mode IM app 一个 goroutine，30s reconcile DB——新增 app 拉起 client、禁用/密钥轮换则 cancel 重建。runClientWithRestart 指数退避封顶 60s。locale：每个 channel 可 pin locale，bridge 在 user content 后追加语言指令（localeDirective），coordinator 再透传给 specialist，避免 GLM 默认中文答英文问题。

没有专门的 "DB specialist"——README 说 "SRE / network / DB sub-agents"，但 agents/ 里实际是 compute/disk/network/ops/sre/investigator/reviewer 七个，DB 诊断目前落在 specialist-ops（service 状态）+ host_bash（mysql/redis 进程）。

mutating 纪律（cmdpolicy + ReviewGate 双闸）：

• ① edge 侧 cmdpolicy（policy.go）：host_bash 的 binary 分五类。systemctl restart 等 write 子命令直接拒（specialist-ops.md 明说"不要用 host_bash 跑 systemctl restart 绕开二审——那条命令在 cmdpolicy 里被拒"）。ip netns exec 因为是"递归 shell 可绕过 cmdpolicy"被显式拒。shells/脚本语言/rm/dd/chmod 全在 ClassDenied。Mixed 类默认拒。
• ② manager 侧 ReviewGate（decorators/review_gate.go）：任何 Class=write|destructive 的工具调用前，自动 spawn reviewer worker 审 proposal，只有解析到 Decision: approve 才放行内层工具；reject/解析失败/spawn 失败一律默认拒（safe default）。spawner 为 nil 时也是 "always reject"，防止误配置。

func isMutatingClass(class string) bool {
    switch strings.ToLower(strings.TrimSpace(class)) {
    case "write", "destructive": return true
    default: return false
    }
}
// 三态：approve→跑内层+MarkExecuted；reject→ErrReviewRejected；解析不出 Decision→ErrReviewUndecided(按reject)

这把"一个大 prompt 干所有事"的脆弱性换成了"小而专的子 agent + 明确边界"，并用 dedupe/MaxTurns/dynamicHints 一整套护栏对抗弱模型的死循环——这是把 SOTA agent 套路（claude-code 的 AgentTool/system-reminder）落到生产 SRE 场景的实践样本。

• Stars 数：未在仓库内体现，待确认（页面展示为「未知 / —」）。
• DB specialist：README 提及 "DB sub-agents"，但 agents/ 仅含 compute/disk/network/ops/sre/investigator/reviewer，独立 DB persona 待确认（当前 DB 诊断落在 specialist-ops + host_bash）。
• DingTalk / WeCom：README 列为支持渠道，但 imbridge/provider/ 仅实现 feishu/slack/telegram，钉钉/企微实现待确认。
• web/ SPA 组件实现：本次只读了 web/src/api/*.ts 层，具体 React 组件（聊天/拓扑/webshell 渲染）实现细节待确认。
• 旧 agent.go 内核：与 graph 内核并存，本文聚焦 graph 内核（runtime.go/worker.go），旧内核细节未深读。