Harness 核心组件与架构
目录
- 总览：一次 Agent 请求的 Harness 切面
- 组件一：编排环（Orchestration Loop）
- 组件二：Context Engineering（上下文组装）
- 组件三：工具网关（Tool Gateway）
- 组件四：记忆与状态（Memory & State）
- 组件五：护栏（Guardrails）
- 组件六：可观测性（Observability）
- 组件七：Eval Harness（离线）
- 参考架构（中小团队）
- 面试可答：Harness 和 Framework 谁负责什么？
- 延伸阅读
总览：一次 Agent 请求的 Harness 切面
从工程视角，Harness 不是单一服务，而是横切在模型调用链上的组件集合。下面按「请求生命周期」排列，便于面试时按顺序讲。
组件一：编排环（Orchestration Loop）
职责：决定「下一步是再调模型、调工具、还是结束」。
| 模式 | 说明 | 适用 |
|---|---|---|
| ReAct | Thought → Action → Observation 循环 | 通用 Agent |
| Plan-Execute | 先出计划再逐步执行 | 步骤清晰的长任务 |
| Graph / State Machine | 节点与边显式定义 | 强合规、可审计 |
| Single-shot + Tools | 模型一次决定是否调工具 | 简单场景 |
Harness 必配参数（无论哪种模式）：
maxSteps/maxToolCalls：防无限循环timeoutMs：整请求与单工具分别设abortSignal：用户取消必须传到模型与工具onStepFinish：每步写 trace，便于调试
Vercel AI SDK 中对应 streamText({ maxSteps: 5, tools, abortSignal })；OpenAI Agents SDK 有内置 run loop。核心思想一致：循环是 Harness 管的，不是模型自觉停的。
组件二：Context Engineering（上下文组装）
在 Harness 内通常独立成 buildMessages(session, task) 模块。
输入源
| 来源 | 说明 | 风险 |
|---|---|---|
| System + Skill | 角色、规范、渐进披露 | 过长占窗口 |
| 会话历史 | 多轮 user/assistant | 噪声累积 |
| RAG 片段 | 检索 top-k | 错检带入幻觉 |
| Tool results | JSON / 文本 | 超大结果撑爆上下文 |
| 结构化状态 | 计划、槽位、中间变量 | 与 history 重复 |
2026 常用策略
- 固定预算：system 20% + RAG 30% + history 40% + 预留 10%
- 摘要压缩：超过 N 轮后对旧 history 做 LLM 摘要（异步、带 cache）
- Prompt Caching：稳定 system 前缀走缓存（Anthropic / OpenAI 等支持），Harness 层保证 system 块稳定
- Tool result 截断：超过 4k token 则摘要或只保留字段子集
- 引用格式统一：RAG 带来源
[doc:12]，便于模型 cite 与前端展示
与 Skills 专题 的关系：Skill 是 Context 的模块化来源；Harness 决定何时加载哪段 Skill（渐进披露）。
组件三：工具网关（Tool Gateway）
模型侧的 function / tool 声明只是「意图」；真正执行必须在 Harness 控制的网关里。
模型 tool_call → 网关校验 → 鉴权 → 执行 → 规范化结果 → 回填 messages
| 网关能力 | 说明 |
|---|---|
| 白名单 | 只允许注册过的 tool name |
| Schema 校验 | Zod / JSON Schema 校验参数 |
| 幂等与去重 | 同一 toolCallId 不重复写库 |
| 沙箱 | 文件/网络/Shell 隔离 |
| 速率限制 | 按 user / tenant 配额 |
| HITL | 敏感操作挂起等人批 |
MCP 把「工具发现 + 传输」标准化；Harness 仍要包一层网关，不能把 MCP Server 直接暴露给不可信输入。见 MCP 开发与应用。
组件四：记忆与状态（Memory & State）
| 类型 | 存储 | Harness 职责 |
|---|---|---|
| 会话内 | Redis / 内存 | 多轮 history、tool 中间态 |
| 跨会话 | DB + 向量库 | 用户偏好、长期事实（需用户同意） |
| 工作记忆 | 当前 run 的变量 | 计划步骤、已收集字段 |
面试点：记忆不是「全塞进 context」；Harness 要做 write policy（什么值得记）和 read policy（什么时候检索注入）。
组件五：护栏（Guardrails）
分三层，与 03-生产Harness七大模式 对应：
- 输入护栏：PII 检测、Prompt 注入规则、请求大小
- 过程护栏：步数、成本上限、工具分类（只读 vs 写）
- 输出护栏：Structured Outputs、拒答模板、内容安全 API
推理模型（o 系列、DeepSeek-R1 等）常带长 chain-of-thought；Harness 应 不把 raw reasoning 全量给前端或日志，只保留 audit 需要的摘要。
组件六：可观测性（Observability）
生产 Harness 最低配：
| 信号 | 字段示例 |
|---|---|
| traceId | 贯穿 HTTP → 每步 LLM → 每次 tool |
| span | stepIndex、model、latencyMs、tokenIn/Out |
| 成本 | 按 trace 汇总 USD / 积分 |
| 结果 | success / timeout / guardrail_block / user_abort |
2026 常见栈：OpenTelemetry + Langfuse / LangSmith / 自建 ClickHouse。前端联调时至少要有 可按 traceId 查全链路 的管理页或日志查询。
组件七：Eval Harness（离线）
在线 Harness 的「镜像环境」：同一套 buildMessages + tools mock，对 Golden Set 批量跑。与在线共用代码路径越一致，回归越可信。详见 05-Eval-Harness与发布门禁。
参考架构（中小团队）
面试可答：Harness 和 Framework 谁负责什么？
Framework（如 Vercel AI SDK）提供 stream、tool 类型、maxSteps 等原语；Harness 是你用这些原语组出来的策略与策略组合：哪些 tool 开放、context 怎么裁、trace 怎么打、失败怎么降级。换 Framework 应尽量只换适配层，Harness 策略层保持稳定。