HiClaw 深度研究：Manager 管一群 Worker，凭证零暴露的安全设计独一份

一、问题之根：为何Harness成了“隐形霸主”？

传统代理工程里，模型只管“想”，真正决定成败的往往是外层那团“胶水代码”——何时调用工具、如何校验输出、失败如何恢复、状态如何流转、何时停止。这便是Harness（驾驭层）。LangChain那句“If you’re not the Model, you’re the Harness”一针见血。

问题在于：这些逻辑高度耦合在控制器代码里，像把铁路信号、时刻表、检票口全焊死在火车头里。想改一条规则？牵一发而动全身。想做消融实验（ablation）看哪个模块真有用？难如登天。想把这套策略复用到另一个场景？几乎重写。

Higress团队一针见血地指出：Harness从未被当作“干净、可研究的对象”。它一直是“偶然的副产品”。

二、论文之破：把策略从代码里“解放”出来

论文提出两个核心物件：

• NLAH（Natural-Language Agent Harnesses）：一份可编辑的自然语言文档（.md足矣）。里面写明：任务阶段划分、角色分工、状态外化规则、校验门（validation gates）、恢复策略、停止条件、产物契约（artifact contracts）。

举例：“在委托子代理前必须先写状态文件到STATE_ROOT”；“未拿到目标文件证据前不得finalize”。

• IHR（Intelligent Harness Runtime）：一个共享的智能运行时，像一位“读文档的聪明管家”。它把NLAH这篇“操作手册”翻译成具体行动：调用哪个agent、更新什么状态文件、触发哪个校验、什么时候交接。

关键分离： 策略层（意图、流程、规则）→ 自然语言文档（人类可读、可改、可版本） 机制层（精确执行、沙箱、解析器、工具适配）→ 仍留在确定性代码里

这就像把“宪法”（高层原则、价值、流程）从“刑法细则”（精确执行条款）里抽出来。宪法可公开辩论、修订；细则由专业机构严格执行。

实验数据很硬核：在SWE-bench Verified、Terminal-Bench 2.0、OSWorld上，IHR执行的NLAH性能与原生Code Harness相当（甚至在某些场景持平或略胜），但策略描述从6万多token压缩到约2900 token。消融实验只需改文档，不动代码，就能测出“文件持久化状态”是稳健正贡献（+2.6%~+13.9%），而“多候选搜索”“上下文压缩”常是负收益或中性。

三、Higress团队的解读：赞在何处？忧在何方？

Higress团队（王晨）解读精准且务实：

大赞之处：

• 把Harness从“黑箱胶水”变成“科学表示对象”。第一次可以像做科学实验一样，对策略模块做leave-one-out消融，归因清晰。
• 可审计、可复用、可移植。换一个.md文件，策略就变了，适合长周期、多场景的代理系统。
• 揭示了工程实践的残酷真相：不是模块越多越好。很多“看起来聪明”的技巧（多候选、激进压缩）实际拖后腿。文件外化状态比依赖模型记忆可靠得多——这点对我们做长期记忆、上下文治理的人尤其扎心。

清醒的忧虑（团队点得狠）：

• 自然语言天生模糊。跨阶段协调机制遵循度明显低于“契约式”机制（后者可即时验证）。模型解读偏差可能悄悄改变行为。
• 外置策略虽降低开发门槛，却扩大了攻击面：提示注入、恶意工具嫁接、供应链污染……都需要溯源、审查、沙箱三重防护。
• IHR原型仍有token与调用开销，生产化尚需打磨。

Higress作为API网关团队，特别在意真实世界部署的边界。他们隐含地指出：NLAH + IHR提供了策略层，但生产环境还需要强基础设施层（沙箱隔离、权限控制、可观测性、流量治理）。这正是Higress能发力的点——在agent工具调用、状态流转、API边界上做“运行时策略增强”。

四、费曼式再解：这到底改变了什么？

想象你开一家“AI打工仔公司”：

• 传统方式：每个打工仔（模型）都背着一本厚厚的《公司作战手册》+《应急预案》，还缝在衣服里。想改规则？得给每个仔重新缝。
• NLAH方式：公司出一本《标准作业流程手册》（.md），清晰写着“第一阶段做什么、第二阶段交给谁、什么情况下必须写日志、什么证据才能交差”。每个仔配一个“现场主管”（IHR），主管拿着手册指挥，仔只管执行精确动作（工具调用、文件读写）。

结果：

• 规则改了，只印新手册就行（可编辑性）。
• 想知道“日志模块到底值不值”？把那一页撕掉跑一遍实验就知道（可消融）。
• 新人来了，直接给手册+主管培训（可复用）。
• 但手册若写得含糊，主管和仔可能各有各的理解（模糊性风险）。

这正是Harness Engineering从“隐性手艺”变成“一等公民学科”的开端。策略不再是代码里的副作用，而是可版本、可审计、可科学优化的对象。

五、对我们实操的启示

一直在深潜代理基础设施（KLIP系列、代理流、上下文治理、RAO自演化）。这篇工作直接击中痛点：

• 可观测性与可控性：把高层策略外置为自然语言 + 文件状态，天然利于长期运行、事后审计、人类介入。
• 演化友好：想试新策略？改文档即可，不用动底层代码。配合你的“Context Mode”与记忆长城，或可做出更优雅的自适应harness。
• 生产落地：纯IHR还不够。需要像Higress这样的网关层，在工具调用、状态流转、权限边界做强约束与观测。沙箱 + 策略文档 + 网关三层，才是真实可信的代理系统。

当然，风险也要正视：自然语言的“各取所需”问题，必须用严格的产物契约 + 沙箱 + 人工审查来对冲。

最终拍板：Higress团队的解读，既看到了论文的范式突破（策略文档化 + 运行时解释），也清醒指出了其边界（精确性、攻击面、生产基础设施）。这不是“用自然语言取代一切代码”的乌托邦，而是在正确边界上把Harness从黑箱变成白箱的一次重要尝试。

Higress 架构与设计思想

本文档基于 Higress 源码（v2.2.2）与仓库内文档深度整理，旨在系统阐述项目的整体架构、核心设计原则与实现思想。更详细的组件原理可参考 architecture.md，用户与开发文档见 higress.cn。

---

目录

1. 项目定位与设计哲学 2. 整体架构 3. 控制面：Higress Controller 4. 数据面：Higress Gateway 5. 管理面：Console 与 hgctl 6. 配置流转与中间表示 7. 插件与扩展体系 8. 服务发现与注册中心集成 9. 核心设计模式 10. 代码仓库结构 11. 技术栈与依赖关系 12. 演进方向与架构取舍 13. 参考资料

---

1. 项目定位与设计哲学

1.1 是什么

Higress 是一款 AI Native 云原生 API 网关，内核基于 Istio 与 Envoy 二次定制，是 CNCF Sandbox 项目。它从阿里巴巴内部为解决 Tengine reload 对长连接业务的损害、gRPC/Dubbo 负载均衡能力不足等生产痛点而诞生，已在阿里内部及大量企业环境中验证。

当前 Higress 承担多重角色：

1.2 设计哲学

Higress 的架构决策围绕以下核心思想展开：

#### 站在巨人肩上，而非重复造轮子

Higress 不重新实现网关数据面，而是深度复用 Envoy 的高性能代理能力与 Istio Pilot 的配置分发机制。控制面的增量工作集中在 Ingress/Gateway API 到 Istio IR 的翻译层 与 Higress 特有 CRD 的处理，避免维护一套独立的 xDS 控制面。

#### 标准优先，降低迁移成本

• 路由配置遵循 Kubernetes Ingress API 与 Gateway API 标准
• 兼容 nginx-ingress 注解，支持从 nginx-ingress 平滑迁移
• 插件配置通过 CRD（WasmPlugin 等） 声明式管理，与 K8s 生态一致

#### 扩展性通过沙箱隔离实现

网关的业务逻辑扩展走 Envoy Proxy-Wasm 沙箱路径，而非修改 C++ 内核或重启进程。Wasm 插件支持 Go / Rust / C++ / JS 等多语言，可独立版本升级，实现 流量无损热更新。

#### 生产级可靠性与 AI 场景友好

• 配置变更毫秒级生效，彻底摆脱 Nginx reload 引起的连接抖动
• 完整流式处理（SSE 等），对大带宽 AI 场景显著降低内存开销
• 阿里内部验证：每秒数十万级请求 的大规模场景

#### 开放与社区驱动

项目遵循 CNCF 治理模型，强调 Openness、Fairness、Community First。完整治理说明见 GOVERNANCE.md。

---

2. 整体架构

Higress 由三大运行时组件构成（Console 为独立仓库）：

┌─────────────────────────────────────────────────────────────────┐
│              Higress Console（higress-console 独立仓库）          │
│         路由 / 插件 / 域名 / 证书管理 UI + Higress Admin SDK      │
└────────────────────────────┬────────────────────────────────────┘
                             │ K8s API / Admin SDK
┌────────────────────────────▼────────────────────────────────────┐
│                   Higress Controller（本仓库）                    │
│  ┌──────────────────────┐    ┌───────────────────────────────┐  │
│  │  Discovery           │    │       Higress Core            │  │
│  │  (Istio Pilot)       │◄───│  Ingress Config + Cert Server  │  │
│  │  Config Controller   │    │  (6+ K8s Controllers)         │  │
│  │  Service Controller  │    │  MCP over xDS 配置来源          │  │
│  └──────────┬───────────┘    └───────────────────────────────┘  │
│             │ gRPC xDS (:15051)                                  │
└─────────────┼────────────────────────────────────────────────────┘
              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Higress Gateway（数据面）                      │
│       Pilot Agent + Envoy（UDS xDS: LDS/RDS/CDS/EDS/SDS）         │
│       Wasm 插件在 HTTP Filter 链中执行                            │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
              上游业务服务 / LLM API / MCP Backend / 注册中心服务

请求处理路径（简化）：

客户端 → Envoy Listener → HTTP Router → Wasm Filter 链 → 上游 Cluster → 后端服务
                ↑                              ↑
           LDS/RDS (xDS)                  WasmPlugin CRD

---

3. 控制面：Higress Controller

控制面是本仓库（cmd/ + pkg/）的核心，通过 higress serve 启动。

3.1 启动链路

cmd/higress/main.go
    └── pkg/cmd/server.go          (cobra: higress serve)
            └── pkg/bootstrap/server.go   (NewServer)
                    ├── initKubeClient
                    ├── initXdsServer          # Istio DiscoveryServer + MCP Generators
                    ├── initHttpServer         # /ready, /debug
                    ├── initConfigController   # IngressTranslation 作为 ConfigStore
                    ├── initRegistryEventHandlers
                    ├── initAuthenticators
                    └── initAutomaticHttps     # Let's Encrypt 自动证书

默认监听端口：

3.2 Discovery 子组件（Istio Pilot-Discovery）

Discovery 负责 服务发现、配置聚合、xDS 推送，是 Istio 控制面的核心。Higress 复用其以下能力：

#### Config Controller

管理多种配置来源，Higress 的关键集成点是 MCP over xDS：

• Higress Core 实现 MCP Server，作为 Discovery 的 Istio 配置来源之一
• higress-config ConfigMap 中 configSources 同时指向本地 xDS 与 K8s：

configSources:
- address: xds://127.0.0.1:15051   # Higress Core (MCP)
- address: k8s://                 # K8s 原生 Istio CRD

#### Service Controller

对接 Kubernetes Service / Endpoint，提供服务发现数据（EDS）。

3.3 Higress Core 子组件

Higress Core 是 Higress 相对 Istio 的 核心增量，位于 pkg/ingress/。

#### Ingress Config（虚拟 ConfigStore）

IngressConfig（pkg/ingress/config/ingress_config.go）实现 Istio 的 ConfigStoreController 接口，是一个 只读、Pull 式 的虚拟配置存储：

• 不 将转换结果写回 Kubernetes
• 在 xDS List(GVK) 被调用时 按需转换 Ingress/Gateway/CRD 为 Istio 中间表示（IR）
• 支持的 IR 类型（pkg/ingress/kube/common/schema.go）：

Gateway · VirtualService · DestinationRule · ServiceEntry · EnvoyFilter · WasmPlugin

#### 六大控制器

另有 Secret Controller（kube/secret/）管理 TLS 证书，KIngress 支持（Knative Ingress 并行处理）。

#### Cert Server

pkg/cert/ 提供 Let's Encrypt 自动签发与续签，监听 higress-https ConfigMap，管理 TLS Secret。

---

4. 数据面：Higress Gateway

数据面由 Pilot Agent + Envoy 组成，镜像来自 Istio/Envoy submodule 构建。

4.1 组件职责

• Pilot Agent：Envoy 生命周期管理，代理 xDS 请求到 Discovery（gRPC → UDS）
• Envoy：高性能 L7 代理，执行路由、负载均衡、TLS 终止、Wasm 插件

4.2 Envoy 核心概念

4.3 HTTP Filter 链

Envoy 的请求处理经过 HTTP Connection Manager 中的 Filter 链。Higress 通过 WasmPlugin 和 EnvoyFilter 在此链中注入：

• Wasm HTTP Filter：通用插件（认证、限流、AI 代理等）
• Golang Native Filter：MCP Server 等需要原生性能的场景
• EnvoyFilter：Http2Rpc 等协议转换

---

5. 管理面：Console 与 hgctl

5.1 Higress Console（独立仓库）

higress-console 提供 Web UI，功能包括：

• 路由、域名、证书、插件、服务来源管理
• 内置或可对接自建 Grafana / Prometheus 可观测

Higress Admin SDK 从 Console 剥离，提供 Java（JDK 17+）API，便于外部系统对接配置管理。

5.2 hgctl CLI（本仓库 hgctl/）

独立 Go module 的命令行工具：

---

6. 配置流转与中间表示

6.1 完整数据流

① 用户提交配置
   ├── K8s Ingress + higress/nginx 注解
   ├── Gateway API (Gateway / HTTPRoute / GRPCRoute / ...)
   ├── Higress CRD (WasmPlugin / McpBridge / Http2Rpc)
   └── ConfigMap (higress-config: 全局配置)

② Informer 同步到本地 Cache
   └── Work Queue.onEvent → 触发 xDS PushRequest

③ xDS DiscoveryServer 收到 Push
   └── MCP Generator.Generate() → Environment.List(GVK)

④ IngressConfig.List(GVK)  [Pull 式转换]
   ├── listFromIngressControllers()
   │     ├── 读取 Ingress → 解析注解 → 转换 IR
   │     └── convertGateway / VirtualService / DestinationRule / ...
   └── listFromGatewayControllers()
         └── GatewayController.List() → krt 已转换的 IR

⑤ MCP Generator 序列化为 xDS MCP Resource
   └── gRPC ADS → Envoy Gateway 应用配置

6.2 Pull 式转换 vs 传统 Reconcile

Higress 控制面 不采用 典型的 Operator Reconcile（读 CR → 转换 → 写回 Status）模式来处理路由配置。其设计是：

1. K8s 资源变更 → 仅触发 xDS Push 信号 2. 实际 Ingress → VirtualService 转换在 xDS List() 调用时按需执行 3. 使用 istio.io/always-push: "true" 标签，跳过 config diff，确保每次事件触发 full push

这种 Event-driven Push + Pull 式 Virtual ConfigStore 模式与 Istio Pilot 原生架构一致，避免了维护转换结果副本的一致性问题。

6.3 Ingress 注解系统

注解处理采用 策略模式 + 责任链，位于 pkg/ingress/kube/annotations/：

AnnotationHandlerManager
├── Parser[]              → 解析注解到 Ingress 结构体
├── GatewayHandler[]      → 应用到 Gateway（如下游 TLS）
├── RouteHandler[]        → 应用到 HTTPRoute（重写、CORS、限流等）
└── TrafficPolicyHandler[]→ 应用到 DestinationRule（负载均衡、上游 TLS）

支持的注解能力包括：金丝雀发布、CORS、重写/重定向、超时/重试、负载均衡、本地限流、认证、镜像流量、Http2Rpc、MCP Server 等。

IngressClass 过滤逻辑：

---

7. 插件与扩展体系

Higress 的差异化能力很大程度来自其 双轨插件架构。

7.1 架构总览

                    ┌─────────────────────────────────┐
                    │         控制面 CRD               │
                    │  WasmPlugin / ConfigMap / CRD   │
                    └───────────────┬─────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              ▼                     ▼                     ▼
     Istio WasmPlugin          EnvoyFilter           ServiceEntry
              │                     │                     │
              ▼                     ▼                     ▼
     ┌────────────────┐   ┌─────────────────┐   ┌──────────────┐
     │ Proxy-Wasm     │   │ Golang Filter   │   │ Http2Rpc     │
     │ HTTP Filter    │   │ (MCP Server)    │   │ 协议转换      │
     └────────────────┘   └─────────────────┘   └──────────────┘
              │                     │
              ▼                     ▼
     plugins/wasm-go/       plugins/golang-filter/
     plugins/wasm-cpp/      plugins/golang-filter/mcp-server/
     plugins/wasm-rust/

7.2 WasmPlugin CRD

API Group： extensions.higress.io/v1alpha1

Higress WasmPlugin 在 Istio WasmPlugin 基础上扩展：

控制面转换链：

WasmPlugin CR → CommonController (Informer)
  → IngressConfig.convertIstioWasmPlugin()
  → Istio WasmPlugin IR
  → WasmPluginGenerator → xDS MCP → Envoy Proxy-Wasm

7.3 插件实现目录（plugins/）

AI 相关插件集群（战略重点）：

• ai-proxy：统一 LLM API 代理，支持 30+ 国内外模型 Provider
• ai-token-ratelimit / ai-quota：Token 级流控
• ai-cache / response-cache：AI 响应缓存
• ai-statistics / ai-load-balancer：AI 可观测与多模型负载均衡
• mcp-server / mcp-router：MCP 协议托管与路由

7.4 Http2Rpc（EnvoyFilter 路径）

Http2Rpc CRD（networking.higress.io/v1）将 HTTP 请求映射为 Dubbo / gRPC RPC 调用，控制面生成专用 EnvoyFilter（constructHttp2RpcEnvoyFilter），不走 WasmPlugin 路径。适用于将遗留 RPC 服务以 HTTP 接口暴露。

7.5 插件设计原则

1. 沙箱隔离：Wasm 插件在 Proxy-Wasm VM 中运行，内存安全，崩溃不影响 Envoy 主进程 2. 热更新无损：OCI 镜像更新后，Envoy 动态加载新模块，长连接不中断 3. 流式友好：SDK 支持完整流式 Body 处理，适配 SSE / AI 流式响应 4. 粒度可控：全局 / 域名 / 路由 / 服务四级 matchRules

---

8. 服务发现与注册中心集成

8.1 McpBridge CRD

API Group： networking.higress.io/v1

声明外部注册中心连接信息，支持：

8.2 Registry Reconciler

registry/reconcile/reconcile.go 采用 Level-triggered Reconcile 模式：

McpBridge CR (desired state)
    → diff vs watchers map (actual state)
    → Create / Update / Delete registry watcher
    → 产出 ServiceEntry + DestinationRule + WasmPlugin
    → 触发 xDS Push

这与 Ingress 控制器的 Event-driven Push 模式不同，Registry Reconciler 是典型的 desired/actual diff + apply 模式，适合管理有生命周期的外部连接（Watcher）。

---

9. 核心设计模式

9.1 关键接口

// 核心控制器 — pkg/ingress/kube/common/controller.go
type IngressController interface {
    RegisterEventHandler(kind, handler)
    List() []config.Config
    ConvertGateway / ConvertHTTPRoute / ConvertTrafficPolicy(...)
    Run(stop) / HasSynced()
}

type GatewayController interface {
    model.ConfigStoreController   // 直接提供转换后的 Istio IR
}

// xDS 集成 — pkg/ingress/mcp/
type XdsResourceGenerator interface {
    Generate(proxy, watchedResource, pushRequest) (Resources, ...)
}

---

10. 代码仓库结构

higress/
├── api/                  # Higress CRD Protobuf 定义 → Cue → CRD YAML
├── client/               # CRD 的 client-go Informer/Lister 生成代码
├── cmd/higress/          # Controller 入口 (higress serve)
├── pkg/
│   ├── bootstrap/        # 服务编排与启动
│   ├── cert/             # 自动 HTTPS 证书
│   ├── cmd/              # Cobra CLI
│   ├── config/           # 全局配置常量
│   ├── ingress/          # ★ 核心：配置翻译 + K8s 控制器 + xDS 生成
│   └── kube/             # 扩展 K8s Client（Higress CRD Informer）
├── registry/             # 外部注册中心 Watcher + Reconciler
├── plugins/              # Wasm 插件 + Golang Filter 源码
├── hgctl/                # CLI 工具（独立 Go module）
├── helm/                 # Helm Charts（controller / gateway / plugin-server）
├── docker/               # Controller 镜像 Dockerfile
├── samples/              # 示例 YAML
├── test/                 # E2E 一致性测试
├── istio/                # Git Submodule：定制 Istio 1.27
├── envoy/                # Git Submodule：定制 Envoy 1.36
└── docs/                 # 仓库内文档

独立关联仓库

---

11. 技术栈与依赖关系

Submodule 与构建：

Istio 与 Envoy 以 Git Submodule 形式 vendored，构建时 go.mod 通过 replace 指向 ./external/*。这允许 Higress 在 Istio/Envoy 上游基础上做必要 fork 而不脱离社区版本节奏。

---

12. 演进方向与架构取舍

12.1 从 Ingress 网关到 AI Gateway

Higress 的架构演进体现了明确的战略路径：

1. 第一阶段：替代 Nginx Ingress — 注解兼容、配置热更新、资源开销降低 2. 第二阶段：微服务网关 — McpBridge 多注册中心、Dubbo 集成、Http2Rpc 3. 第三阶段（当前重点）：AI Gateway + MCP Gateway — ai-proxy 插件族、MCP Server 托管、统一 LLM/MCP API 管理

架构上，AI 与 MCP 能力 并未引入新的控制面组件，而是通过 Wasm 插件 + CRD 扩展 在现有 Envoy Filter 链上叠加，体现了「扩展而非重写」的设计哲学。

12.2 关键架构取舍

12.3 未来可扩展方向

• Gateway API 支持持续增强（InferencePool 等 AI 相关 API）
• MCP Generator Delta xDS 实现（当前 TODO）
• 多集群 / 多 Revision 配置隔离
• 更丰富的 AI 插件生态（RAG、Agent Workflow 等）

---

13. 参考资料

仓库内文档

• architecture.md — 核心组件与原理（含架构图）
• README_ZH.md — 项目介绍与使用场景
• GOVERNANCE.md — CNCF 治理模型
• CONTRIBUTING_CN.md — 贡献指南
• plugins/wasm-go/README_EN.md — Wasm Go 插件开发

官方在线文档

• Higress 是什么
• 架构介绍
• MCP 快速开始
• Wasm 插件开发电子书

上游项目

• Envoy 官方文档
• Istio 流量管理
• Gateway API
• Istio Pilot 组件介绍（赵化冰）

---

*文档版本：基于 Higress v2.2.2 源码整理*