驾驭工程（Harness Engineering）

位置：LLM 应用工程四层演进的第四层（最高层 / 最外层） 调研日期：2026-05-01

Executive Summary

Harness Engineering（驾驭工程） 这个术语在 2026 年 2 月由 Mitchell Hashimoto（HashiCorp 创始人）在 My AI Adoption Journey [44] 第 5 步首次正式命名。触发事件之一是 OpenAI 在同月发表的 Harness Engineering: Leveraging Codex in an Agent-First World [47]——OpenAI 内部产品实验团队描述他们如何在 5 个月、3-7 名工程师、约 100 万行代码、约 1500 个 PR、零行手写源代码的条件下用 agent 完成产品迭代。Hashimoto 读后给了它一个名字。

Hashimoto 给的原始定义是 verbatim 这一句——它后来成为整个领域的精神坐标 [44]：

“It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again.” （这个理念是：每当你发现 agent 犯了错，你就花时间工程出一个解，让它再也不可能犯这个错。）

OpenAI 给同一件事的工程化等式是 Agent = Model + Harness，分工原则是一句金句 [47]：

“Humans steer. Agents execute.”（人类掌舵，agent 执行。）

Anthropic 在 Effective Harnesses for Long-Running Agents [45] 给出实证发现，把所有 harness 的目的浓缩成一条定律：

“Successfully solving a problem with a coding agent is strongly correlated with the agent’s ability to verify its own work.” （能不能用 coding agent 真正解决问题，强相关于这个 agent 能不能验证自己的工作。）

把三家观点合在一起：驾驭工程的全部目的，是让模型只走”已经被验证为安全且能被验证为正确”的路径。这导出两条核心法则——本章把它们作为一切组件的脊柱：

• 法则一：强约束（Strong Constraints / Engineer-It-Out）——能用确定性约束（lint / type / sandbox / CI 硬失败）的地方，永远不要用提示词。
• 法则二：自愈循环（Self-Healing Loops / Evaluator-Optimizer）——agent 必须能从环境里拿到”地面真相”，能自我评估、能自我修正、能在失败后从 checkpoint 恢复。

§3.3.1-§3.3.3 是 harness 工程强约束的直接实现（MCP / 沙箱 / 护栏），§3.9 附录给相关但非 harness 的 4 类支撑设施（网关 / 推理 / 观测 / 评估）。

本章覆盖：

• §3.1 起源（Hashimoto 2026-02 命名 + Karpathy 反转工作流 + OpenAI 内部架构曝光）
• §3.2 与提示词 / 上下文 / Agent 三层的边界
• §3.3 驾驭工程的核心方法论 + 支撑设施：
  • §3.3.0 核心方法论（这是 harness 工程的”是什么”）：
    • 两条核心法则（哲学层 / 为什么）：强约束（环境工程消除错误） × 自愈循环（agent 自己验证自己）
    • 四大支柱（功能层 / 做什么，参考 OpenAI/Anthropic/Stripe 实践收敛）：
      1. 上下文架构（Context Architecture）——给 agent 一张地图，不是百科全书
      2. Agent 专业化（Agent Specialization）——多角色 × 工具权限差异化
      3. 持久化记忆（Persistent Memory）——进度落在文件系统而非上下文
      4. 结构化执行（Structured Execution）——理解→规划→执行→验证四阶段
  • §3.3.1-§3.3.3 Harness 强约束的 3 个直接实现：工具集成（MCP，定义 ACI 契约）、沙箱（E2B/microVM，OS 物理层）、护栏（NeMo Guardrails，输入/输出 4 道墙）
  • §3.9 附录 相关但非 harness 的 4 类基础设施品类（任意 LLM 应用都需要）：LLM 网关（LiteLLM/Portkey）、推理服务器（vLLM/SGLang）、可观测性（Langfuse）、评估（DeepEval/RAGAS）
• §3.4 完整生产栈参考架构图 + §3.4.6 Harness 成熟度模型 L0-L4（自我诊断）
• §3.5 四层演进 + §3.5.4.5 熵管理与黄金原则（agent-first 团队的隐形配套）
• §3.6 三类典型场景的选型清单（个人学习 / 创业 MVP / 企业生产）
• §3.7 Limitations + 完整 Bibliography（50+ 条）+ Methodology Appendix

Agent 编排框架（LangGraph / AutoGen / CrewAI 等）属于 Agent 工程层，已迁移到 agent-engineering.md §5。

3.1 起源：被命名的”那一层东西”

3.1.1 Hashimoto verbatim：每犯一次错，工程消除一次

“Harness Engineering”作为术语在 2026 年 2 月由 Mitchell Hashimoto 正式命名。其原文出自他自己的 My AI Adoption Journey 第 5 步 Engineer the Harness，verbatim 引用 [44]：

“I’ve grown to calling this ‘harness engineering.’ It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again.” （我越来越把这件事叫做”驾驭工程”。每当你发现 agent 犯了错，你就花时间工程出一个解，让它再也不可能犯这个错。）

Hashimoto 紧接着指出 harness 有两种形态——这是后续所有 harness 实践的源头分类 [44]：

“This comes in two forms… Better implicit prompting (AGENTS.md). For simple things, like the agent repeatedly running the wrong commands or finding the wrong APIs, update the AGENTS.md. Each line in that file is based on a bad agent behavior, and it almost completely resolved them all.” “Actual, programmed tools. For example, scripts to take screenshots, run filtered tests, etc.”

合起来：harness 的最便宜入口是 AGENTS.md（每行 = 一次 agent 错误的封堵）；上限是真正写出来的工具脚本。Hashimoto 还给了一条效率定律——“agents are much more efficient when they produce the right result the first time”——这正是为什么强约束（让它不可能错）和好工具（让它一次跑对）都重要。

3.1.2 OpenAI 的工程化等式：Agent = Model + Harness

触发 Hashimoto 命名的是 OpenAI 在 2026 年 2 月发表的 Harness Engineering: Leveraging Codex in an Agent-First World [47]——OpenAI 内部产品实验：5 个月、3-7 名工程师、约 100 万行代码、约 1500 个 PR、零行手写源代码。这篇文章把 harness 工程提到 control plane 高度，并提出了角色分工的金句：

“Humans steer. Agents execute.”（人类掌舵，agent 执行。）[47]

OpenAI 自己用一组强约束撑起了这种规模——例如把团队的工程审美 / 设计哲学编码成一组小规则 taste invariants，全部以 CI 硬失败强制执行，没有 warning 这一档；依赖按 Types → Config → Repo → Service → Runtime → UI 单向流动，由结构性测试机械守住 [47][8]。

3.1.3 Anthropic 的实证定律：Verifier 决定上限

Anthropic 在 Effective Harnesses for Long-Running Agents [45] 给出的关键发现，是后续所有 harness 设计的最强约束：

“Successfully solving a problem with a coding agent is strongly correlated with the agent’s ability to verify its own work.” （能不能用 coding agent 真正解决问题，强相关于这个 agent 能不能验证自己的工作。）

如果一个 agent 缺少自验证机制，再强的模型 + 再多的提示词也只是把”看起来完成”和”真的完成”混淆起来。Anthropic 在同一篇里给出他们自己 Claude Agent SDK 的设计应对：长任务用 Initializer + Coding Agent 双角色、强制 git commit + progress file 作为 memory bridge、给 agent 配 浏览器自动化工具让它像人类用户一样测试——后者 “dramatically improved performance, as the agent was able to identify and fix bugs that weren’t obvious from the code alone” [45]。

3.1.4 Karpathy 的工作流反转：harness 让”agent 主写”成为可行

Karpathy 在 2025-2026 年多次描述自己的 coding workflow 已经从”主要手写代码、偶尔让 agent 帮忙”反转成”主要由 agent 写代码、自己手动微调”。让这种工作模式可行的不是模型变强，而是 agent 周围的环境——repo 结构、CI 配置、formatter、package manager、framework 约束、project instruction、外部工具集成、linter——这些一起构成了 agent 的 “harness”。

Adnan Masood 在 2026 年 4 月 Medium 文章 Agent Harness Engineering: The Rise of the AI Control Plane [32] 用 control plane 框架做了同样的总结：

「Harness Engineering 是构建那个 governs 一个已部署 AI agent 跨多次交互的整个系统——guides、sensors、data context pipelines、eval suites、constraint enforcement。」

3.1.5 一句话定义

把上面四家的观点合在一起：驾驭工程是一门学科，目标是让模型只走”已被验证为安全且能被验证为正确”的路径。它通过两条法则达成：(1) 强约束——把可能出错的事情工程性消除；(2) 自愈循环——让出错也能自动收敛回正轨。 这把”AI 安全”和”AI 工程化”统一到了同一条原则：约束环境，而非约束模型本身。模型能力是可变的（每三个月升一代），但环境约束是稳定的、可累积的。

3.1.6 数据冲击：瓶颈在基础设施，不在模型智能

很多团队在 Agent 编程效率不高时第一反应是”换更强的模型”。但 2026 年多个独立实验证明：仅改 harness 设计、不动模型权重，就能带来数量级性能提升。

“五个独立团队，得出了相同结论：瓶颈在基础设施，不在模型智能。 在纠结模型选择之前，先审视 Harness 设计——能获得更高的投资回报率。”

这条数据有更深的政策含义：Harness 是负成本投资——它带来的提升不靠贵模型而靠工程纪律。下面 §3.2 起讲怎么做。

3.2 与其他三层的边界

四层抽象的清晰划分：

类比：

• prompt = 你给员工的一个具体指令
• context = 员工桌面上能看到的所有材料（笔记本、邮件、文档、聊天记录）
• agent = 员工本人，能根据目标和材料自主完成多步工作
• harness = 公司的整套规章、工具、CI 流程、code review、教练系统

3.3 驾驭层：核心方法论 + 支撑设施

驾驭工程的核心方法论由两层构成：

• 哲学层（“为什么”）= 两条核心法则：强约束（工程消除错误） + 自愈循环（让出错自动收敛）
• 功能层（“做什么”）= 四大支柱：上下文架构 / Agent 专业化 / 持久化记忆 / 结构化执行

这两层都是 harness 工程的特征性内容——它们回答”什么样的工程实践才叫 harness”。

§3.3.1-§3.3.3 列的 3 个组件（工具集成 / 沙箱 / 护栏 — harness 强约束的直接实现）；§3.9 附录给相关但非 harness 的 4 类基础设施（网关 / 推理 / 观测 / 评估）则是支撑性基础设施——任意生产 LLM 应用都需要的基础设施品类。它们是 harness 跑起来的依赖项，不是 harness 工程的方法论特征。读者请把 §3.3.0（方法论）+ §3.3.1-§3.3.3（强约束的直接实现）当作 harness 工程；§3.9 附录是相关但非 harness 的支撑设施。前者是 harness 的”是什么”，后者是”在什么之上跑”。

之前版本把这 7 类称为”七大组件”是不恰当的合成命名——它们更准确地叫”驾驭层的支撑性基础设施品类”。LLM 网关、推理服务器、可观测性这些在任何 LLM 应用栈里都需要，并不是 harness 工程的特点。本节订正这个框架问题。

3.3.0 核心方法论：两条法则 + 四大支柱

3.3.0.1 法则一：强约束（Strong Constraints / Engineer-It-Out）

核心断言：在 prompt 里写”请遵守 X”和在 CI 里加一个看到违反 X 就挂掉构建的 lint，是两件根本不同的事情。前者是概率性遵守，后者是确定性约束。能用确定性约束的地方，永远不要用提示词。

Augment Code 在 Harness Engineering for AI Coding Agents [8] 给出的最锋利对照：

“Telling an agent ‘follow our coding standards’ in a prompt is fundamentally different from wiring a linter that blocks the PR when standards are violated. The first approach relies on probabilistic compliance; the second enforces deterministic constraints.” （在 prompt 里跟 agent 说”请遵守编码规范”，和接一个会在违规时直接挂掉 PR 的 linter，是根本不同的两件事。前者依赖概率性遵守，后者强制执行确定性约束。）

强约束在 2026 年的工程实践有 6 个典型抓手：

(1) 三层强化系统（Augment Code 框架 [8]）

实施顺序：先 constraint，再 feedback，最后 gate——constraint 在其他东西就位前就先压低失败量；feedback 让自我修正不再依赖人；gate 拦下前两层挡不住的东西 [8]。

(2) Lint message 本身就是给 agent 的 prompt [8]

"violation detected" 这种报错只能让人看懂；agent 看到这种报错只会反复重试或绕开。一个能让 agent 自动修复的 lint，必须把”该怎么改”写进报错本身：

❌ "console.log violation detected"
✅ "Use logger.info({event: 'name', ...data}) instead of console.log to keep structured logging."

“The lint message itself becomes a prompt.” — Augment Code [8]

并且：关掉 // eslint-disable-next-line 这类行内禁用——否则 agent 会用”压住报错”代替”修掉报错”。同样的思路推广到 # type: ignore、@SuppressWarnings、#pragma 等所有”绕过检查”的语法糖：在 agent 主导的 codebase 里，这些都应该被禁用 [8]。

(3) OpenAI 的 taste invariants → CI 硬失败 [47][8]

“OpenAI’s production system enforces what it calls taste invariants: a small set of rules that encode the team’s engineering standards and design philosophy, including general coding conventions and reliability requirements. All are enforced as hard CI failures, not warnings.”

把”团队审美”——通用编码规范、可靠性要求、依赖方向——全部编码成一组小规则，全部以 CI 红色构建强制执行，没有 warning 这一档。OpenAI 自己的依赖单向流动 Types → Config → Repo → Service → Runtime → UI 由 structural tests（架构适配函数）守住——agent 写出违反分层的 import，CI 会直接挂掉。

(4) Deny-First 权限系统（Claude Code 模型 [49]）

Claude Code 的 permission 系统用 deny → ask → allow 三段式优先级，deny 永远优先，任何上层的 allow 在某层 deny 后立刻失效：

// .claude/settings.json — 强约束式权限配置
{
  "permissions": {
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(rm -rf ~)",
      "Read(./**/.env*)",
      "Read(./**/id_rsa*)",
      "Write(./**/.git/**)",
      "WebFetch(domain:internal.corp)"
    ],
    "ask": [
      "WebFetch",
      "Bash(git push:*)",
      "Bash(rm -rf:*)"
    ],
    "allow": [
      "Bash(git diff:*)",
      "Bash(git status:*)",
      "Read", "Edit"
    ]
  }
}

“Rules are evaluated in order: deny → ask → allow. The first matching rule wins, so deny rules always take precedence. If a tool is denied at any level, no other level can allow it.” [49]

即使在 bypassPermissions 模式下，rm -rf / 和 rm -rf ~ 仍会强制提示——作为”防模型抽风”的最后一道断路器 [49]。

(5) 防御纵深：permission（软围栏）+ OS sandbox（硬围栏）[49]

Claude Code 文档里说得很直白：

“Effective sandboxing requires both filesystem and network isolation. Without network isolation, a compromised agent could exfiltrate sensitive files like SSH keys. Without filesystem isolation, a compromised agent could backdoor system resources to gain network access.” [49]

“Even if an attacker successfully manipulates Claude Code’s behavior through prompt injection, the sandbox ensures your system remains secure.” [49]

permission 是逻辑层的软围栏（agent 自己看 rules 决定是否绕路），sandbox 是 OS 层的硬围栏（macOS Seatbelt / Linux bubblewrap / Linux user namespace，子进程也跑不出去——kubectl、terraform、npm 都受限）。两者必须叠用，单独任何一层都不够。Devin 用一台一次性 VM per task 是同一思路的另一种实现 [50]。

(6) Pre-execution Validation Gates (PEV) [47][8]

在工具调用真正执行之前的四道检查——这是把 LLM 决策从工具效果中解耦的关键墙：

# Pre-execution gates 伪代码（同样可以做成 PreToolUse hook）
def pev_gate(tool_call):
    if tool_call.name not in WHITELIST:                    # 1. 工具白名单
        raise Reject("unknown_tool")
    if not tool_call.args.matches(SCHEMA[tool_call.name]): # 2. 参数 schema 校验
        raise Reject("invalid_args")
    if tool_call in DANGEROUS:                              # 3. 危险动作必须 ask
        if not user_approved(tool_call):
            raise Reject("approval_required")
    if tool_call.has_path() and not in_workspace(tool_call.path):  # 4. 路径越界
        raise Reject("path_outside_workspace")
    return ALLOW

OpenAI 的实现把这四道做在 LLM 决策之前，任意一道失败就直接拒绝——在 LLM 还没拿到工具响应之前就把脏请求杀掉。Claude Code 的 PreToolUse hook（exit code 2）等价 [49]。

(7) 上下文 40% 预算硬约束（Smart Zone vs Dumb Zone）

强约束不只在工具/权限层。Context budget 也必须强约束——这是 2026 年长任务 agent 失败的最常见根因。经验法则（来自多家长任务 agent 团队的复测）：

┌────────────────────────────────────────────────────┐
│  ✅ Smart Zone（前 40%）       ❌ Dumb Zone（>40%）│
│  ─────────────────────────     ───────────────────│
│  • 聚焦推理                    • 幻觉 / 循环      │
│  • 精炼信息                    • 工具调用格式错   │
│  • 输出质量高                  • 代码质量崩塌     │
└────────────────────────────────────────────────────┘
                ↑ 红线 40% （以 168K 窗口为例）

工程化落地：在 orchestrator 里加一道强约束闸门——if context_used / context_max > 0.4 就强制触发 (a) 摘要压缩 / (b) 移交给新 sub-agent / (c) 写 progress 文件后开新会话。不能依靠 LLM 自己”觉得太长了”——它感觉不到，往 90% 装也照塞。这条规则把 §3.3.0.2 (5) 的 “progress file + git memory bridge” 反向耦合到一个可机械触发的阈值上。

(8) Agent 知识边界：“看不到的等于不存在”

“if it cannot be enforced mechanically, agents will deviate.”

OpenAI 在百万行代码实验中给的最锋利总结之一 [47]。直接推论：任何不在 agent 可机械读取范围内的”知识”都不存在于 agent 的世界里。

工程意义：当你发现 agent 反复违反一个”明明大家都知道”的规范——根本原因 100% 是这个规范没进 git。强约束的最低门槛：把它写成 git 里的文件，不管是 lint rule、markdown 文档还是 schema。“那次 Slack 讨论对齐了团队的架构模式？如果它不在代码库里，对 agent 来说就和三个月后入职的新员工一样——根本不知道发生过。” [47]

(9) AGENTS.md：作”目录”而非”百科全书” + 知识库分层

Hashimoto 发明 AGENTS.md 时定位是”每行 = 一次错误的封堵” [44]。但 OpenAI 的百万行实验给出更精确的 do/don’t [47]：

OpenAI 的知识库结构 [47]（可直接抄作团队模板）：

AGENTS.md             # ~100 行，作为地图和目录（不写细节，只写指针）
ARCHITECTURE.md       # 顶层领域与包分层映射
docs/
├── design-docs/      # 设计文档目录，含验证状态
│   ├── index.md
│   ├── core-beliefs.md
│   └── ...
├── exec-plans/       # 执行计划（版本化）
│   ├── active/      # 进行中
│   ├── completed/   # 已完成
│   └── tech-debt-tracker.md
├── product-specs/    # 产品规格
└── references/       # 参考资料

配套的强约束 [47]：依赖按 Types → Config → Repo → Service → Runtime → UI 单向流动；跨切关注点（Auth / Telemetry / Feature Flags / Connectors）只通过单一显式接口 Providers 注入，其余一律由 lint 拒绝。

核心心法：让 agent 物理上无法犯错，比让它”知道不该犯错”可靠 100 倍。

3.3.0.2 法则二：自愈循环（Self-Healing Loops / Evaluator-Optimizer）

核心断言：把”做错→发现→改正”做成 agent 自己能跑的算法。一个无法自我验证的 agent 是不可能在生产里跑长任务的——这是 Anthropic 给出的实证定律 [45]：

“Successfully solving a problem with a coding agent is strongly correlated with the agent’s ability to verify its own work.”

(0) 先看靶子：Anthropic 总结的 4 种典型失败模式

设计自愈循环之前，要先认清 agent 在长任务里到底以什么方式翻车。Anthropic 在 Effective Harnesses for Long-Running Agents [45] 把数千次长跑的失败归纳为 4 类——这 4 类恰好对应自愈循环的 4 个工程化抓手：

记住这 4 类靶子——下面 7 个抓手不是堆栈而是这 4 个失败模式的对应工程化解。

(1) 标准范式：Evaluator-Optimizer（Anthropic 6 大 agentic pattern 之一）

Anthropic Building Effective Agents [46] 把这个范式正式化为 6 大 agentic pattern 之一：

“In the evaluator-optimizer workflow, one LLM call generates a response while another provides evaluation and feedback in a loop.”

       ┌─── generate ──────────┐
       │                       ▼
   ┌───┴────┐             ┌────────┐
   │ Actor  │             │Evaluator│
   │ (LLM)  │◀── feedback │  (LLM) │
   └────────┘             └────┬───┘
                               │
                          ground truth
                          (test/lint/CI/browser)

关键：evaluator 必须有”地面真相”输入——单纯的”另一个 LLM 来评分”会落入 §3.9.4.3 的三大 bias。Anthropic 原文说得清楚 [46]：

“During execution, it’s crucial for the agents to gain ‘ground truth’ from the environment at each step (such as tool call results or code execution) to assess its progress.”

适用条件 [46]：

“This workflow is particularly effective when we have clear evaluation criteria, and when iterative refinement provides measurable value.”

判据：(a) 人类反馈能带来可观的改进；(b) LLM 自己也能给出这种反馈。两条都满足 → 装 evaluator。两条都不满足 → 不要硬上，因为评估本身的成本可能压垮主任务。

(2) 学术原型三件套

Reflexion 的概括：“self-reflective feedback acts as a ‘semantic’ gradient signal”——用自然语言而不是梯度做”强化学习”。这正是工业界 evaluator-optimizer 的学术对应物 [51]。

(3) Verification 驱动开发（最小骨架）

让 agent 自己跑测试 / linter / type checker / 浏览器，把失败信号当 prompt 喂回去：

def actor_critic_loop(task, max_iter=5):
    code = actor.generate(task)
    for i in range(max_iter):
        result = run_tests(code)        # ★ ground truth：测试 / lint / type check
        if result.passed:
            return code
        # 失败信号变成结构化 prompt
        feedback = (
            f"Iteration {i+1}: tests failed.\n"
            f"Failures:\n{result.errors}\n"
            f"Hints: {result.hints}\n"
            f"Fix the implementation. Do not modify or skip the failing tests."
        )
        code = actor.refine(code, feedback)
    raise FailedToConverge(f"after {max_iter} iterations")

Anthropic Effective Harnesses for Long-Running Agents [45] 的实战经验：给 agent 浏览器自动化工具让它像人类用户一样测试 → “dramatically improved performance, as the agent was able to identify and fix bugs that weren’t obvious from the code alone”。代码层 + 行为层双 verifier 是 Claude Code 等顶级 coding agent 在 2026 年仍能跑长任务的根本原因 [45]。

(4) Verifier rejection 必须以结构化反馈喂回去 [47][8]

当 verifier 拒了一个实现，绝不可默默丢弃——拒绝本身要变成下一次生成的 context：

“When the Verifier rejects an implementation, the rejection becomes a structured context for correction rather than being silently dropped.” [47][8]

工程意义：你的 CI / lint / test runner 必须能输出机器可读的失败原因（locator + reason + suggested fix），而不只是 stack trace。这又回到法则一第 (2) 条——lint message 本身就是 prompt。

(5) Progress file + git 作为 memory bridge（Anthropic 长任务范式 [45]）

长任务 agent 会跑爆 context window。Anthropic 的解法：

• Initializer agent 做一次性的脚手架搭建 + 写出长 spec
• Coding agent 每次会话只做一个 feature，结束时强制 git commit + 写 progress 文件
• 下一次会话从 progress 文件 + git log 重启
• 关键：用 git 回退能力恢复到最近一个 working state

“It’s still essential that the model leaves the environment in a clean state after making a code change. We found that the best way to elicit this behavior was to ask the model to commit its progress to git with descriptive commit messages and to write summaries of its progress in a progress file.” [45]

“This allowed the model to use git to revert bad code changes and recover working states of the code base.” [45]

(6) 适应性 × 确定性保障：retry + checkpoint + resume [52]

Anthropic How we built our multi-agent research system [52] 的设计原则：

“Letting the agent know when a tool is failing and letting it adapt works surprisingly well. We combine the adaptability of AI agents built on Claude with deterministic safeguards like retry logic and regular checkpoints.”

“When errors occur, we can’t just restart from the beginning: restarts are expensive and frustrating for users. Instead, we built systems that can resume from where the agent was when the errors occurred.”

具体落地：

• 每次工具调用后做 checkpoint（trace_id + state snapshot）
• 失败时按 exponential backoff 重试 N 次
• 超过阈值不重启整个 agent，而是从 checkpoint 恢复 + 让 agent 知道刚才哪个工具失败了
• LLM 的”语义适应”和系统的”确定性重试”必须叠加：纯靠 LLM 重试会打乱状态，纯靠系统重试会丢上下文

(7) 在线评估 → 自动告警 → 自动回滚 → 反向耦合到强约束

观测+评估+护栏三件套合起来才是闭环：

Observability (trace, §3.9.3)        ← 看到了什么
        ↓
Evaluation (LLM-as-judge / RAGAS, §3.9.4)  ← 好不好
        ↓
Alerting (quality drift)              ← 漂移告警
        ↓
Auto-rollback / Canary                ← 自动回退到上一个 good 版本
        ↓
Failure → AGENTS.md / new lint / new deny rule  ← Hashimoto 闭环
        ↓
        永远不能再以同样方式发生

最后一步——Hashimoto 的核心闭环——把”这一次的失败”工程性消解掉，让它永远不能再发生 [44]。这是把”自愈循环”反向耦合回”强约束”的关键节点：每一次自愈循环触发，都应该问一句”这是 prompt 不够好，还是 harness 该再加一道墙？“——后者优先。

3.3.0.3 两条法则的耦合 + 向四大支柱过渡

两条法则告诉你为什么要建 harness——但当你坐下来动手时，需要一个”做什么”的功能分解。下面 §3.3.0.4 起的四大支柱就是这个功能层；它们和两条法则不是替代关系，而是 WHY × WHAT 的两个互补镜头：

诊断方式：把团队最近一次 agent 事故拿出来对照 4 支柱，问哪根支柱垮了——

“事故是因为 agent 看到了不该看的（支柱 1 上下文）／用了不该用的工具（支柱 2 专业化）／忘了上次干到哪（支柱 3 记忆）／还是跳过了规划阶段就开干（支柱 4 执行）？”

答案命中的那根支柱，就是下个 sprint 该补的。

3.3.0.4 四大支柱：harness 的功能分解

参考自 OpenAI [47] / Anthropic [45] / Stripe / Cloudflare 等独立团队 2026 年早期实践的收敛——下面 4 个支柱是 harness 工程”做什么”层面的事实标准。注意：

• 4 支柱是功能层（functional decomposition），不是采购清单
• 每根支柱都有 §3.3.0.1（强约束）/ §3.3.0.2（自愈循环）的具体抓手作为它的实现机制
• §3.3.1-§3.3.3 列的”工具集成 / 沙箱 / 网关 / …“是支撑性基础设施品类，不是 harness 方法论的特征

3.3.0.5 支柱一：上下文架构（Context Architecture）

“Agent 应当恰好获得当前任务所需的上下文——不多不少。给 Agent 一张地图，而不是一本百科全书。”

实施 = 4 件套（与 §3.3.0.1 强约束抓手一一对应）：

(1) 上下文三层 Tier 渐进式披露

(2) AGENTS.md 作目录而非百科全书

详见 §3.3.0.1 第 (9) 点：~100 行作为地图（指针而非细节）+ docs/ 目录分层 + 配套 lint 校验文档结构。

(3) 上下文 40% 硬约束 Smart/Dumb Zone

详见 §3.3.0.1 第 (7) 点：超过 40% 强制摘要压缩 / 移交 sub-agent / 写 progress 文件后开新会话。

(4) Agent 知识边界

详见 §3.3.0.1 第 (8) 点：“if it cannot be enforced mechanically, agents will deviate.” Agent 看不见 Slack / Wiki / 邮件 / 口头约定——任何规范要生效，必须落进 git。

3.3.0.6 支柱二：Agent 专业化（Agent Specialization）

“专注于特定领域、拥有受限工具的 Agent 优于拥有全部权限的通用 Agent。 思考与执行分离，避免上下文污染。”

5 种典型角色 + 工具权限矩阵

实施

每个角色一个独立 sub-agent，用 §3.3.0.1 第 (4) 点的 deny-first 权限系统给每个角色配独立的 settings.json——研究 agent 只能 Read，执行 agent 只能写指定路径，清理 agent 只能改特定规则类。

// .claude/agents/researcher.settings.json — 研究 agent 专用
{
  "permissions": {
    "deny": ["Write", "Edit", "Bash(*:write*)"],
    "allow": ["Read", "Grep", "Glob", "Bash(git log:*)"]
  }
}

详细的多角色协作模式见 agent-engineering.md §5（5 大模式：sequential / parallel / supervisor / debate / hierarchical）。

3.3.0.7 支柱三：持久化记忆（Persistent Memory）

“进度持久化在文件系统上，而非上下文窗口中。 每次新 Agent 会话从零开始，通过文件系统制品重建上下文。”

详细机制见 §3.3.0.2 第 (5) 点（progress file + git 作 memory bridge）。本支柱补充 Anthropic Effective Harnesses for Long-Running Agents [45] 给的标准会话开机协议——每个长任务 agent 必须遵守的 5 步启动流程：

1. 运行 pwd 查看工作目录
2. 读取 git log 和 progress 文件，了解最近的工作
3. 读取 feature list 文件，选择最高优先级的未完成功能
4. 启动开发服务器，运行基础端到端测试
5. 确认基本功能正常后，开始新功能开发

把这 5 步写进 AGENTS.md，并让 orchestrator 在每次会话开始强制 agent 跑一遍——这条强约束直接阻止了 §3.3.0.2 第 (0) 点列出的”环境启动困难”失败模式。

3.3.0.8 支柱四：结构化执行（Structured Execution）

“将思考与执行分离。 研究和规划在受控阶段进行，执行基于验证过的计划。”

实施 = 4 阶段强制工作流：

🔍 理解 → 📋 规划 → ⚡ 执行 → ✅ 验证
   ↑                              ↓
   └──── 失败回 evaluator-optimizer ───┘ （§3.3.0.2 (1)）

“永远不要让 Agent 在你审查和批准书面计划之前写代码。 这种规划与执行的分离是我做的最重要的一件事。” — Boris Tane, Cloudflare（业界广为引用）

CI 作为 harness 核心组件——机械化约束而非文档约定：架构边界 / 依赖方向 / taste invariants / 黄金原则全部以 CI 硬失败强制（详见 §3.3.0.1 第 (3) 点 + §3.5.4.5 熵管理）。

3.3.1 工具集成层（Tool Integration）

从这里开始的 §3.3.1-§3.3.3 是”支撑性基础设施”——任何生产 LLM 应用都需要的 7 类基础设施品类（每类有 2+ 公开市场对比来源 [37][38][39][40][33][34][35][36]）。它们是运行 harness 的依赖项，不是 harness 工程的方法论特征——真正的方法论是上面的 §3.3.0（两条法则 + 四大支柱）。本节是工具选型清单。

详见 context-engineering.md §2.7 的 MCP / A2A 协议层介绍。除此之外驾驭层关心的实施面：

• Function Calling：LLM provider 原生（OpenAI、Anthropic、Google、DeepSeek 都支持），适合简单工具、单 LLM provider 场景
• MCP：跨 LLM、可复用、生态爆发中（97M 月下载）—— 2026 年的事实标准
• OpenAPI / GraphQL adapter：把任意 REST/GraphQL 服务包成 MCP server
• Agent Skills（Anthropic 2026 推出）：把”agent 知道如何做某类任务”打包成可复用单元

实战：MCP 已是 2026 年的事实标准，新项目直接 MCP，老项目通过 MCP adapter 兼容。

3.3.2 沙箱与代码执行（Sandbox）

agent 写代码 / 跑命令 / 处理用户上传文件，必须在隔离环境里。详细 sandbox 方案对比见 agent-engineering.md §10.4。这里只列驾驭层选型：

• E2B：开源 + SaaS 都有，secure sandbox 跑任意 Python / Node / Bash，毫秒级冷启
• Daytona：开源 dev environment，原本面向 dev container，2025 起加 agent sandbox 支持
• Modal：serverless GPU + sandbox 双用
• OpenAI Code Interpreter（Apps SDK）：托管，简单
• Anthropic Claude Computer Use：让 Claude 操作桌面应用，本质是更激进的 sandbox

最低限度：绝不在生产服务器主进程里 eval() agent 输出。即使是看起来无害的 os.path.join。

guardrails">3.3.3 护栏（Guardrails）

LLM 是不可信组件。它会幻觉、会被注入、会泄密、会生成有害内容。护栏是放在 LLM 输入和输出两侧的”过滤层”。2026 年主流：

• NVIDIA NeMo Guardrails [36]：开源，用 Colang DSL 描述对话流和约束。支持 5 种 rails（见 §3.3.3.4 详解）
• Guardrails AI（开源）：Pydantic 风格的”validator”，校验 LLM 输出符合 schema、不含 PII、不含越狱触发词
• AWS Bedrock Guardrails：托管护栏，AWS 生态零接入
• Azure Content Safety：同上，Azure 生态
• Lakera Guard：商用 prompt injection 检测专精
• Protect AI Layer：商用全栈安全平台

实战配置：

• 输入侧：prompt injection 检测 + PII 过滤 + 主题白名单
• 检索侧：检索结果按敏感度分级，敏感内容不进 LLM
• 输出侧：PII / 敏感词检测、事实性验证、JSON schema 校验、长度 / 速率限制
• 审计侧：所有”被护栏拦下”的请求记录，定期 review

3.3.3.1 OWASP LLM Top 10（2025 版）Top 3 深度

OWASP Top 10 for LLM Applications (2025) 是业界 LLM 安全风险的标准分类法，与 MITRE ATLAS 框架对齐。前 3 名是生产 agent 必须先解决的：

LLM01: Prompt Injection

LLM 把”上下文里的指令”和”用户/工具/检索内容”无法可靠区分。任何能写入 context 的渠道都是攻击面：

Remediation tree：

1. 隔离：system / user / tool 三类内容用结构化 channel 而非字符串拼接（Anthropic message API、OpenAI roles）
2. 检测：输入 / 工具结果都过 prompt-injection classifier（Lakera / PromptGuard / Llama Guard）
3. 最小权限：注入即使发生，也无法执行高破坏性动作（deny-first 工具权限）
4. 输出审计：可疑动作（外发数据、删除、转账）触发二次确认或 HITL
5. 永不假设可解决：Anthropic / OpenAI 公开承认 prompt injection 短期无完美解，必须靠”权限隔离 + 审计”兜底

LLM02: Sensitive Information Disclosure

LLM 把训练数据 / system prompt / RAG 私密 chunk / 其他用户数据”漏”给当前用户。

主要风险：

• 训练数据记忆（PII / 邮件 / 密码）
• RAG 跨租户串数据（用户 A 的检索结果出现在用户 B 的回答里）
• system prompt 含 API key / 内部 URL 被套出
• LLM 在错误 / debug 信息里把内部 schema / 表名暴露

Remediation：

1. 训练数据脱敏：自训模型必须 PII removal + canary tokens 检测
2. 多租户强隔离：RAG / Memory 强制 user_id 过滤（见 context-engineering.md §2.5.9）
3. System prompt 不含密钥：所有 secret 走 env / KMS，prompt 里只引用变量名
4. 输出 PII scanner：用 Presidio / Llama Guard 在输出层再过一道
5. 错误消息脱敏：不返回 stack trace 给用户，只返回通用错误码

LLM03: Supply Chain

依赖的模型 / 数据集 / 插件 / MCP server 被恶意篡改。

主要风险：

• HuggingFace 上下载的模型权重被植入后门
• pip install 一个看起来合法的 LLM 库实际盗 API key
• MCP server 来自第三方，访问范围超出声明
• 微调数据集被投毒（少量样本就能植入触发词）

Remediation：

1. 模型 / 数据集 hash 验证（HuggingFace 已支持 revision= 锁版本）
2. MCP server 白名单 + 沙箱运行 + 输出 audit
3. 训练数据 provenance（来源可追溯）+ 异常样本检测
4. 依赖审计（pip-audit / Snyk）+ 锁版本

完整 OWASP Top 10 清单（2025）：LLM01 Prompt Injection / LLM02 Sensitive Info Disclosure / LLM03 Supply Chain / LLM04 Data and Model Poisoning / LLM05 Improper Output Handling / LLM06 Excessive Agency / LLM07 System Prompt Leakage / LLM08 Vector and Embedding Weaknesses / LLM09 Misinformation / LLM10 Unbounded Consumption。

3.3.3.2 Jailbreak 攻击 Taxonomy 与防御

Jailbreak 攻击家族详细分类参见 prompt-engineering.md §1.6.3 —— DAN / Roleplay / Instruction Override / Encoding / Many-shot / Cipher / Token smuggling / RAG injection / CoT injection 共 8 大类。

Harness 层的 jailbreak 防御策略（不能只靠 RLHF / system prompt）：

经验：单一防御层平均拦截率 60-80%，三层叠加可到 95%+。生产 agent 至少做”输入 + 输出 + 工具结果”三层。

3.3.3.3 EU AI Act 2026-08 高风险义务清单

EU AI Act（Regulation EU 2024/1689）2024-08-01 生效，高风险 AI 系统的强制义务于 2026-08-02 起执行。这是全球首部全面 AI 立法，影响所有在欧盟运营或服务欧盟用户的 AI 产品。

风险分级：

• Unacceptable Risk（禁止）：社会评分、subliminal manipulation、批量人脸识别（除特定执法）、情绪识别（工作 / 教育场景）
• High Risk（高风险，强制义务）：教育评估 / 招聘 / 信贷 / 保险 / 执法 / 司法 / 医疗诊断 / 关键基础设施 / 边境管理
• Limited Risk：聊天机器人 / deepfake → 透明度义务（用户必须知道在与 AI 交互）
• Minimal Risk：垃圾邮件过滤、游戏 AI 等 → 鼓励自愿守则

高风险系统的 9 项强制义务（Article 8-15 + 16-29）：

1. Risk Management System —— 全生命周期识别、评估、缓解风险，文档化
2. Data Governance —— 训练 / 验证 / 测试数据集质量管理，bias 评估
3. Technical Documentation —— 模型架构 / 训练方法 / 性能 / 局限性文档（Annex IV）
4. Record Keeping —— 自动日志保存，覆盖 input / output / 决策依据，至少 6 个月
5. Transparency to Users —— 告知用户在使用 AI 系统，提供使用说明
6. Human Oversight —— 设计上必须可被人 override / halt / interpret，HITL 不是可选
7. Accuracy / Robustness / Cybersecurity —— performance 指标公开，对抗 prompt injection 等攻击有防御
8. Quality Management System (QMS) —— ISO 9001-style 质量体系
9. Conformity Assessment + CE Marking —— 上市前合规评估，标记 CE 标志

违反代价：最高 €35M 或 全球年营收 7%（取较高者），高于 GDPR。

对工程团队的具体影响：

• 高风险场景必须有完整的 observability + audit log（Langfuse / OpenLLMetry / 自建）
• HITL 不能是”形式上的”，必须有人真正可以 halt + override
• Foundation model 提供方（OpenAI / Anthropic / Mistral）有额外的 GPAI 义务（透明度报告 / 训练数据摘要 / 系统性风险评估）
• 必须能复现单次决策的依据 —— 这倒推出”每次推理 trace + RAG chunk + system prompt 全留存”

实操路径：

1. 先判断你的产品是不是 high-risk（用 EU 官方 risk classification questionnaire）
2. 是 → 立刻接入 observability + audit log + HITL 机制
3. 准备 Annex IV 技术文档模板
4. 找通过 notified body 做 conformity assessment
5. 部署后持续 post-market monitoring

3.3.3.4 NeMo Guardrails 5 大 Rails 详解

NVIDIA NeMo 用 Colang DSL 把 5 类 rails 编排成一个对话状态机：

5 rails 的覆盖与误报权衡：

• 全开：拦截率最高（~95%），但误报率达 5-10%，用户体验差，token 成本翻倍（每次 5+ 次额外 LLM 调用）
• 仅 Input + Output：拦截率 ~80%，误报 1-2%，是大多数生产产品的甜点
• 仅 Output：兜底配置，prompt injection 几乎无防御
• 配合 NVIDIA Nemotron Safety models：用专用小模型替代 LLM-as-classifier，延迟和成本降一个数量级

最小 Colang 配置：

# config/rails.yml
rails:
  input:
    flows:
      - check jailbreak
      - check pii
  output:
    flows:
      - self check output
  retrieval:
    flows:
      - check sensitive context

完整 Colang 实战见 §3.4.5 F。

3.3.3.5 Deny-First 权限矩阵（实现细节）

Deny-first 的概念见 agent-engineering.md §10.1，harness 层的实现要点：

# 权限矩阵 = (role × tool × scope) → allow / ask / deny
PERMISSION_MATRIX = {
    "default": {  # 默认 role
        "read_file": {"scope": "/workspace/**", "decision": "allow"},
        "write_file": {"scope": "/workspace/**", "decision": "ask"},
        "shell": {"scope": "*", "decision": "deny"},  # deny by default
        "http_get": {"scope": "https://api.internal/*", "decision": "allow"},
        "http_post": {"scope": "*", "decision": "ask"},
        "delete_file": {"scope": "*", "decision": "deny"},
    },
    "trusted_dev": {  # 高信任 role
        "shell": {"scope": "/workspace/**", "decision": "allow"},
        "delete_file": {"scope": "/workspace/.cache/**", "decision": "ask"},
    },
}

# 优先级：deny > ask > allow（任一 deny 即拒绝）
def resolve_permission(role, tool, target):
    rules = [PERMISSION_MATRIX["default"].get(tool)]
    rules.append(PERMISSION_MATRIX.get(role, {}).get(tool))
    decisions = [r["decision"] for r in rules if r and matches_scope(r["scope"], target)]
    if "deny" in decisions: return "deny"
    if "ask" in decisions: return "ask"
    return "allow" if "allow" in decisions else "deny"  # unknown = deny

关键点：

• 未识别动作默认 deny，不要默默放行
• ask 必须有超时和默认拒绝（避免 §9.1.5 Approval Wait Deadlock）
• scope 必须是规范化路径（避免 .. / 软链接 / URL 大小写绕过）
• 审计 log 记录所有 ask / deny，定期 review 调整矩阵

Agent 层面的安全权限模型（deny-first / HITL / 沙箱方案）详见 agent-engineering.md §10。

3.4 完整生产栈参考架构

把所有组件串起来，2026 年一个”教科书式”的生产 agent 系统大致是这样。注意图中两条法则的落点——左侧 ║ 标记的是强约束（在 LLM 决策之前/之后阻断），右侧 ⟲ 标记的是自愈循环（环境反馈回流到 actor）：

                  ┌──────────────────────────┐
                  │   用户 / 前端 / API Client │
                  └────────────┬─────────────┘
                               │
                  ┌────────────▼─────────────┐
                  │   API Gateway / Auth     │
                  └────────────┬─────────────┘
                               │
   强约束 ║      ┌────────────▼─────────────┐
   ─────── ║      │   Guardrail（输入侧）    │  ← prompt injection / PII
                  └────────────┬─────────────┘
                               │
   强约束 ║      ┌────────────▼─────────────┐
   ─────── ║      │   PEV 闸门（4 道检查）   │  ← 工具白名单/参数schema/
                  │   PreToolUse hook        │     批准/路径越界  [47][49]
                  └────────────┬─────────────┘
                               │
                  ┌────────────▼─────────────┐  ◀───────── ⟲ Verifier feedback
                  │   Agent Orchestrator     │             （evaluator-optimizer
                  │   （ReAct / Plan-Execute）│              loop, ground truth
                  │   Actor + Critic + Refiner│             from env）  [45][46]
                  └─┬────┬────┬─────────────┘
                    │    │    │
         ┌──────────▼┐ ┌─▼──┐ ┌▼──────────────┐
         │  Memory   │ │RAG │ │  Tools (MCP)  │  强约束 ║ scope/path 白名单
         │ (Letta /  │ │    │ │  Sandbox(E2B) │  强约束 ║ OS-level Seatbelt
         │  mem0)    │ │    │ │   ↑ ground    │           bubblewrap
         │ progress  │ │    │ │     truth ⟲  │  ⟲ test/lint/browser 反馈
         │   .md     │ │    │ │               │
         │  +git ⟲   │ │    │ │               │
         └─────┬─────┘ └─┬──┘ └─┬─────────────┘
               │         │      │
               └─────────┼──────┘
                         │
                  ┌──────▼─────────┐
   强约束 ║       │  LLM Gateway   │  ← LiteLLM / Portkey
   ─────── ║      │  deny-first    │     密钥/配额/PII redaction
                  │  路由 / 缓存   │  ⟲ fallback / retry / circuit breaker
                  └──────┬─────────┘
                         │
                ┌────────┼─────────┬──────────┐
                ▼        ▼         ▼          ▼
          ┌────────┐┌────────┐┌────────┐┌────────────┐
          │ OpenAI ││Anthropic││ Google ││ vLLM/SGLang│
          │  API   ││  API    ││  API   ││ 自部署 OSS │
          └────────┘└────────┘└────────┘└────────────┘

   ⟲ 自愈闭环：Observability (Langfuse) → Evaluation (DeepEval/RAGAS)
              → Alert (drift) → Auto-rollback / Canary
              → Hashimoto 反向耦合：失败写回 AGENTS.md / lint / deny rule  [44]

   ║ 强约束旁路：输出侧 Guardrail（NeMo / Guardrails AI）+ output schema 校验

两条法则的解读：

• ║ 强约束（5 处）：输入 Guardrail / PEV 闸门 / Tools scope / Sandbox OS 隔离 / Gateway deny-first——任意一处放行，整条链就再也不应当依赖”提示词请求 agent 守规矩”。
• ⟲ 自愈循环（4 处）：Verifier feedback → Actor、tools result 作为 ground truth、git+progress 文件作为 memory bridge、Observability+Eval 闭环 → 自动回滚 → Hashimoto 反向耦合到强约束。

每个箭头都是一个”被驾驭”的接口。错一次，先问”这是 harness 的强约束没盖住，还是自愈循环没建起来？“——再加一条 deny rule、一个 verifier、一个 eval case、一个 guardrail 规则——这就是 harness engineering 的日常 [44][8]。

3.4.5 实战配置示例集（含 harness 与基础设施）

前面 §3.3.1-§3.3.3（MCP / 沙箱 / 护栏，harness 强约束的直接实现）+ §3.9.1-§3.9.4（网关 / 推理 / 观测 / 评估，相关但非 harness 的基础设施）描述了”是什么”，本节补足”怎么配”。下面 A-E 对应 §3.9 附录（基础设施配置），F-H 对应 §3.3.1-§3.3.3（harness 实现配置），I-J 对应 §3.3.0 方法论本身（两条法则）的实操示例。

A. LLM 网关：LiteLLM（自托管 + 多 provider routing + fallback）

config.yaml：

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-6
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: deepseek-v3
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY

router_settings:
  routing_strategy: "least-busy"   # least-busy / latency-based / cost-based
  num_retries: 3
  request_timeout: 30
  fallbacks:
    - gpt-4o: ["claude-sonnet", "deepseek-v3"]   # 失败级联
    - claude-sonnet: ["gpt-4o", "deepseek-v3"]
  cooldown_time: 30                # 单 provider 失败后冷静期
  allowed_fails: 3                 # 失败 N 次进 cooldown

litellm_settings:
  cache: true
  cache_params:
    type: "redis"
    host: "localhost"
    ttl: 3600                      # cache 1h
  set_verbose: false

general_settings:
  master_key: sk-...
  database_url: "postgresql://..."  # 计费 / quota / audit log

启动：

litellm --config config.yaml --port 4000
# 业务代码就用 OpenAI SDK，base_url 指向 http://localhost:4000

B. 推理服务器：vLLM 与 SGLang 启动对比

vLLM 启动：

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 4 \           # 4 卡张量并行
  --max-model-len 32768 \
  --gpu-memory-utilization 0.92 \      # 显存利用率
  --enable-prefix-caching \            # ★★★ 自动复用相同前缀的 KV
  --enable-chunked-prefill \           # 长输入 prefill 分块
  --speculative-model meta-llama/Llama-3.2-1B-Instruct \  # 推测解码 draft
  --num-speculative-tokens 5 \
  --max-num-batched-tokens 8192 \
  --port 8000

SGLang 启动（同硬件、多轮对话场景）：

python -m sglang.launch_server \
  --model-path meta-llama/Llama-3.1-70B-Instruct \
  --tp 4 \
  --context-length 32768 \
  --mem-fraction-static 0.85 \
  --enable-radix-cache \                # ★★★ RadixAttention 自动 KV 复用
  --schedule-policy lpm \               # longest-prefix-match 调度
  --speculative-algorithm EAGLE \
  --speculative-draft-model-path meta-llama/Llama-3.2-1B-Instruct \
  --port 30000

实测经验：单轮独立请求 vLLM 略胜；多轮对话 / agent 工作流（请求间共享前缀大）SGLang 吞吐 +10-30%。

C. 可观测性：Langfuse 接入（3 种姿势）

# 1. LangChain 自动接入：一行
from langfuse.langchain import CallbackHandler
handler = CallbackHandler()
chain.invoke({"input": "..."}, config={"callbacks": [handler]})

# 2. 装饰器：包任何函数
from langfuse.decorators import observe
@observe()
def my_agent_step(query):
    response = llm.invoke(query)
    return response

# 3. OpenAI SDK drop-in 替换：业务零改动
from langfuse.openai import openai
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    metadata={"trace_user_id": "u_42", "trace_session_id": "s_x"},
)

D. 评估：Promptfoo 配置（CI/CD gating）

promptfooconfig.yaml：

prompts:
  - "summarize this in <50 words: {{text}}"
  - "用不超过 50 字总结：{{text}}"

providers:
  - openai:gpt-4o-mini
  - anthropic:claude-haiku-4-5
  - vertex:gemini-2.5-flash

tests:
  - vars:
      text: "Transformer 是 2017 年提出的注意力机制架构..."
    assert:
      - type: contains-any
        value: ["注意力", "attention"]
      - type: latency
        threshold: 3000        # 必须 <3s
      - type: cost
        threshold: 0.001       # 必须 <$0.001
      - type: llm-rubric
        value: "总结忠实于原文且不超过 50 字"
        provider: openai:gpt-4o   # judge model

  - vars:
      text: ""               # edge case
    assert:
      - type: not-contains
        value: "I'm sorry"   # 模型不能借口拒答

defaultTest:
  options:
    repeat: 3                 # 每个 case 跑 3 次取平均（抗 flakiness）

# CI 门：所有断言通过率必须 ≥95%
threshold:
  pass-rate: 0.95

跑：promptfoo eval && promptfoo view。在 GitHub Actions / GitLab CI 里 npx promptfoo@latest eval 失败即 block PR。

E. 评估：RAGAS 评测 RAG 质量（Python）

from ragas import evaluate
from ragas.metrics import faithfulness, context_precision, context_recall, answer_relevancy
from datasets import Dataset

# 黄金集：question, ground_truth, contexts (来自你的 RAG), answer (来自你的 RAG)
data = Dataset.from_dict({
    "question": [...],
    "ground_truth": [...],
    "contexts": [[...], [...]],   # 检索回的 chunks
    "answer": [...],              # 生成的答案
})

result = evaluate(
    data,
    metrics=[faithfulness, context_precision, context_recall, answer_relevancy],
)
print(result)
# {"faithfulness": 0.87, "context_precision": 0.81, ...}

Faithfulness < 0.8 通常意味着模型在编造（应该都是从 context 里来的）。Context recall < 0.7 意味着检索召回不够（要调 retriever）。

F. 护栏：NeMo Guardrails Colang 示例

config.yml：

models:
  - type: main
    engine: openai
    model: gpt-4o
rails:
  input:
    flows: [check_jailbreak, check_pii]
  output:
    flows: [check_factual]
  retrieval:
    flows: [filter_sensitive]

rails.co（Colang 2.0 DSL）：

# 越狱检测
flow check_jailbreak
  $allowed = await call_llm prompt="""
    判断用户输入是否在尝试越狱（绕过安全策略）：
    {{ user_message }}
    回答 yes 或 no。
  """
  if $allowed == "yes"
    bot say "抱歉，我不能讨论这个话题。"
    abort

# PII 过滤
flow check_pii
  $pii = await detect_pii text=$user_message
  if $pii.has_pii
    $user_message = $pii.redacted

# 输出事实性自检
flow check_factual
  $claims = await extract_claims text=$bot_message
  for $c in $claims
    $supported = await check_claim claim=$c context=$retrieved_docs
    if not $supported
      bot say "我对这个细节不确定，建议你再核实。"
      abort

启动：nemoguardrails server --config=./config。业务代码用 OpenAI SDK 把 base_url 指过来，护栏自动生效。

G. 沙箱：E2B Python 代码执行最小示例

from e2b_code_interpreter import Sandbox

# 启动 microVM 沙箱（~125 ms 冷启）
with Sandbox.create() as sbx:
    # 跑 LLM 生成的代码（绝对不能在主进程跑）
    execution = sbx.run_code("""
        import pandas as pd
        df = pd.read_csv('uploaded.csv')
        print(df.describe())
    """)

    # 拿结果（stdout / stderr / 生成的图 / 中间变量）
    print(execution.text)
    if execution.error:
        print(f"沙箱里报错: {execution.error}")

    # 上传文件 / 下载文件 / 网络白名单
    sbx.files.write("uploaded.csv", csv_bytes)
    download = sbx.files.read("output.png")

在 agent 里把这个包成 tool：

@tool
def execute_python(code: str) -> str:
    """在隔离沙箱里跑 Python 代码，返回 stdout/stderr"""
    with Sandbox.create() as sbx:
        result = sbx.run_code(code, timeout=30)  # ★ 超时强制 30s
        return result.text or f"ERROR: {result.error}"

H. 工具集成：MCP Server 最小实现

# my_mcp_server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-server")

@mcp.tool()
def get_weather(city: str) -> str:
    """查询某城市当前天气"""
    # 调真实天气 API
    return f"{city} 当前 22°C 晴"

@mcp.resource("weather://forecast/{city}")
def get_forecast(city: str) -> str:
    """获取 7 天预报"""
    return forecast_data

if __name__ == "__main__":
    mcp.run(transport="stdio")

注册到 Claude Desktop / Claude Code（~/.config/claude/mcp_servers.json）：

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/path/to/my_mcp_server.py"]
    }
  }
}

任何支持 MCP 的 client（Claude / Cursor / Cline / 自研 agent）都能立即调用。

I. 强约束：Pre-commit Hook 作为 Agent 的确定性闸门

让 agent 想绕也绕不开的最便宜入口——pre-commit 钩子。把”agent 可能犯的每一类错”工程性消除：

.pre-commit-config.yaml：

repos:
  - repo: local
    hooks:
      # 1. 禁止 console.log（强制结构化日志）
      - id: no-console-log
        name: "No console.log (use structured logger)"
        entry: bash -c 'grep -rn "console\.log" src/ && echo "Use logger.info({event,...}) — see docs/logging.md" && exit 1 || exit 0'
        language: system
        pass_filenames: false

      # 2. 禁止 inline-disable（防 agent 用"压住报错"代替"修掉报错"）
      - id: no-inline-disable
        name: "No eslint-disable / type:ignore / SuppressWarnings"
        entry: bash -c 'grep -rn -E "eslint-disable-next-line|type:\s*ignore|@SuppressWarnings" src/ && exit 1 || exit 0'
        language: system
        pass_filenames: false

      # 3. 守住分层：Service 层不能直接 import UI
      - id: arch-fitness-service-no-ui
        name: "Architecture: service layer must not import ui/"
        entry: bash -c 'grep -rn "from ui\." src/service/ && exit 1 || exit 0'
        language: system
        pass_filenames: false

      # 4. 任何 secret-looking pattern 都拒绝
      - id: no-secrets
        name: "Secret detection (gitleaks)"
        entry: gitleaks protect --staged --redact
        language: system
        pass_filenames: false

  # 5. 现成工具
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.11.0
    hooks: [{id: mypy, args: [--strict]}]
  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: v0.6.0
    hooks: [{id: ruff, args: [--fix, --exit-non-zero-on-fix]}]

把这套接进 CI（pre-commit run --all-files 作为必过 step），就实现了 Augment Code [8] 的 “constraint harness → feedback → quality gate” 三层中的 quality gate 层。关键：错误信息要把”该怎么改”写在 entry 里——这才是给 agent 看的 prompt，不是给人看的报错。

J. 自愈循环：Evaluator-Optimizer Pattern 最小可运行实现

Anthropic 6 大 agentic pattern 之一 [46]，参考 Anthropic Cookbook 的 patterns/agents/evaluator_optimizer.ipynb。完整 actor-critic-refiner 闭环 + 跨家族 judge + ground truth 接入：

import subprocess
from anthropic import Anthropic
from openai import OpenAI

actor = Anthropic()      # 写代码
evaluator = OpenAI()      # 跨家族当评判官，规避 self-preference bias

ACTOR_SYS = """You are a coding agent. Write Python code for the task.
After receiving feedback, fix the issues without modifying or skipping tests."""

EVAL_SYS = """You are a strict code reviewer. Given the task, code, and test output,
return JSON: {pass: bool, issues: [{file, line, reason, suggested_fix}]}.
- pass=true ONLY if all tests passed AND no critical issues remain.
- Provide concrete, actionable suggested_fix strings (not "fix the bug").
"""

def run_ground_truth(code: str) -> dict:
    """跑测试 / lint / type check：这是 evaluator 必须依据的地面真相"""
    with open("solution.py", "w") as f:
        f.write(code)
    test = subprocess.run(["pytest", "-x", "--tb=short"], capture_output=True, text=True)
    lint = subprocess.run(["ruff", "check", "solution.py"], capture_output=True, text=True)
    types = subprocess.run(["mypy", "--strict", "solution.py"], capture_output=True, text=True)
    return {
        "tests_passed": test.returncode == 0,
        "test_output": test.stdout + test.stderr,
        "lint_clean": lint.returncode == 0,
        "lint_output": lint.stdout,
        "types_clean": types.returncode == 0,
        "types_output": types.stdout,
    }

def evaluator_optimizer_loop(task: str, max_iter: int = 5) -> str:
    code = actor_generate(task)
    history = []
    for i in range(max_iter):
        gt = run_ground_truth(code)             # ★ 地面真相
        verdict = evaluator_judge(task, code, gt)  # ★ 跨家族 LLM judge

        if verdict["pass"] and gt["tests_passed"]:
            return code                          # ✓ 收敛

        # ★ verifier rejection 必须以结构化反馈回传，不能默默丢弃 [47][8]
        feedback = format_feedback(verdict["issues"], gt)
        history.append({"iter": i, "verdict": verdict, "gt": gt})
        code = actor_refine(code, task, feedback, history)

    # ★ 不收敛时不要静默 fallback：要把所有 iteration 喂回上层
    raise FailedToConverge(
        f"after {max_iter} iterations, last issues: {verdict['issues']}",
        history=history,
    )

def actor_generate(task: str) -> str:
    resp = actor.messages.create(
        model="claude-opus-4-7",
        system=ACTOR_SYS,
        max_tokens=4096,
        messages=[{"role": "user", "content": task}],
    )
    return extract_code(resp.content[0].text)

def actor_refine(code: str, task: str, feedback: str, history: list) -> str:
    resp = actor.messages.create(
        model="claude-opus-4-7",
        system=ACTOR_SYS,
        max_tokens=4096,
        messages=[{
            "role": "user",
            "content": f"Task: {task}\n\nPrevious code:\n```python\n{code}\n```\n\n"
                       f"Verifier feedback:\n{feedback}\n\n"
                       f"Iteration {len(history)}/{5}. Fix and return full corrected code."
        }],
    )
    return extract_code(resp.content[0].text)

def evaluator_judge(task: str, code: str, gt: dict) -> dict:
    resp = evaluator.chat.completions.create(
        model="gpt-5",                           # ★ 跨家族判官
        temperature=0,                            # ★ 确定性
        response_format={"type": "json_object"},
        messages=[
            {"role": "system", "content": EVAL_SYS},
            {"role": "user", "content":
                f"Task:\n{task}\n\nCode:\n{code}\n\nGround truth:\n{json.dumps(gt, indent=2)}"
            },
        ],
    )
    return json.loads(resp.choices[0].message.content)

这段代码同时实现了五件事： 1. Evaluator-optimizer pattern（Anthropic 6 大 pattern 之一）[46] 2. Ground truth 来自环境（pytest / ruff / mypy）[46] 3. Verifier rejection as structured context（不默默丢弃）[47][8] 4. 跨家族 judge（规避 self-preference bias，详见 §3.9.4.5） 5. 失败可观测（不收敛时把 history 抛给上层，反向耦合到 §3.9.3 trace）

进一步演化：把 failed_to_converge 事件接进 §3.9.3 的 alert，再在每周回顾时把”这一类不收敛”翻译成新的 pre-commit / lint / AGENTS.md 条目——完成 Hashimoto 闭环 [44]。

3.4.6 Harness 成熟度模型 L0–L4：自我诊断你在哪一级

驾驭工程不是 0/1 命题。下面这套 5 级阶梯（综合 OpenAI / Anthropic / Stripe 等独立团队的实践规律 [47][45]）让团队能定位自己当前位置和下一步动作。核心规律：每升一级，agent 自主权扩大一档，工程师身份越靠近”架构师 + 质量把关者”。

Level 4 标志性能力：完全自主端到端 Bug 修复链

验证代码库状态 → 复现 Bug → 录制失败视频 → 实现修复
   → 验证修复 → 录制成功视频 → 开 PR → 响应 review 反馈 → 合并

整条链路无人介入。能跑通这 9 步，意味着团队同时具备了：自动化测试 / 浏览器自动化 verifier / progress 文件协议 / PR 自动化 / review-bot / 自动 merge gate。

自我诊断 5 问

把团队最近 30 天的事故和瓶颈对照下面 5 题：

1. AGENTS.md / .cursorrules / CLAUDE.md 等”agent 守则”文件存在且每周都在更新吗？（决定 L0 → L1）
2. CI 必须挂掉的规则集 ≥10 条 吗？lint message 包含”该怎么改”吗？（决定 L1 → L2）
3. 你的 agent 有 ≥3 个不同角色（研究 / 规划 / 执行 / 审查），每个角色权限不同吗？（决定 L2 → L3）
4. 是否存在无人值守跑 ≥2 小时且事后能从 progress 文件 + git log 完整还原的长任务？（决定 L3 → L4）
5. 是否存在自动化垃圾回收 agent 定期清理”AI slop”？（巩固 L4，见 §3.5.4.5）

每多答一个 yes，往上爬一级。不要跳级——L1 没夯实就上 L3 多 agent，几乎一定崩成”多个互相污染的不可观测黑盒”。

3.5 Synthesis：四层演进的全貌

3.5.1 时间叙事

把过去四年的行业焦点拉成时间轴：

• 2022-2023：提示词工程时代
  • ChatGPT 引爆、人人写 prompt
  • 主要技术：CoT、Few-shot、ReAct
  • 工程产物：prompt template、prompt 库、prompt 培训课
  • 隐喻：“能跟模型说话的人”
• 2024：上下文工程兴起
  • Karpathy 命名、Anthropic 推动
  • 长上下文（100K → 1M）+ RAG 成熟 + 记忆系统涌现
  • 主要技术：RAG、向量库、reranker、MCP（11 月）
  • 隐喻：“能给模型搭舞台的人”
• 2025：Agent 工程化
  • LangGraph 等框架成熟、Coding Agent 商业化（Claude Code / Cursor / Devin）
  • Computer Use 出现（Anthropic 2024-Q4）
  • 主要技术：状态机、HITL、多 agent、MCP 生态、agent benchmark
  • 隐喻：“能让 LLM 自己做事的人”
• 2026：驾驭工程成为生产关键
  • Hashimoto 命名、OpenAI 内部架构曝光、Karpathy 反转工作流
  • 真实事故频发（Amazon Kiro / Replit / Loop of Death）
  • 主要技术：MCP（97M 月下载）、推理服务器、LLM 网关、可观测性、评估、护栏、合规（EU AI Act 2026-08）
  • 隐喻：“能驯服一群 agent 的工程经理”

3.5.2 四层叠加而非替代

不是替代而是叠加。一个生产级 agent 四层都需要：

• 不写好 prompt（第 1 层）→ 模型理解不了任务
• 不管好 context（第 2 层）→ 模型看不到完成任务必需的信息
• 不建好 agent loop / 框架（第 3 层）→ agent 单步对、整体跑偏
• 不建好 harness（第 4 层）→ 系统在生产里不可控、不可靠、不可演进

3.5.3 工程师能力栈的迁移

• 2022 年最值钱的能力是”能调出模型最佳输出的 prompt 直觉”
• 2024 年最值钱的能力是”能架一套 RAG 让公司所有文档可问”
• 2025 年最值钱的能力是”能搭出能跑的 agent + 选对框架”
• 2026 年最值钱的能力是”能搭一套 agent harness 让多个 agent 在生产 7×24 跑而不出大事故”

下一站很可能是”能把多个 agent harness 联邦化的协议工程师”——A2A 协议生态成熟、多公司 agent 互操作的时代。

3.5.4 跨四层的 7 个共性原则

1. 测量先于优化：没有 eval 数据、没有 dashboard、没有 baseline，所有”提升”都是幻觉
2. 简单优先：80% 的任务用 baseline 方案够了；只在 baseline 失败的地方加复杂度
3. 可观测压倒一切：trace、log、metric 三件套是生产 agent 的氧气
4. 防御性编程：假设模型会幻觉、会被注入、会超时、会断网
5. 可逆设计：每一步都能回滚，每个组件都能换掉
6. 成本意识：每个决策都问”这一步多少 token / 多少 USD / 多少毫秒”
7. 演进式迭代：先 prompt → 不够加 context → 不够建 agent → 不够建 harness。不要从 day 1 就建复杂栈

3.5.4.5 熵管理：技术债是复利贷款，最好每日偿还

强约束 + 自愈循环还有第三个隐形配套——熵管理。Agent 会复制代码库里已存在的模式，包括不均匀或次优的模式，这就是 OpenAI 称为”熵”的漂移现象 [47]。随着代码量增长，熵的积累速度会超过人工清理的速度——在 agent-first 团队尤其明显，因为生成吞吐量是人写的 3-10 倍，而 review 吞吐量只是 2-3 倍。

黄金原则示例（直接编进自定义 lint，违反就挂 CI）[47]：

• 优先使用共享工具包而非手滚 helper，保持不变量集中
• 不”YOLO 式”探测数据——验证边界或依赖类型化 SDK
• 结构化日志格式统一，文件大小不超过约定上限
• 跨切关注点（auth / telemetry / feature flags / connectors）只通过 Providers 注入，其余一律拒绝

“在人类优先的工作流中，这些规则可能感觉迂腐或束缚。在 agent 工作流中，它们成为乘法器——一旦编码，就同时应用于所有地方。” [47]

工程化落地：每周/每天起一个独立的”清理 agent”（read-write 权限受限于”重构一类规则”），让它扫一遍代码库，找出违反黄金原则的地方，开 PR、跑 CI、自动合并。这本质上是把 §3.3.0 两条法则反向应用在 agent 自己的产出上——把熵当成另一个需要被强约束 + 自愈的对象。

核心心法（Manus 团队半年重写 5 次 harness 的总结）：harness 应该越做越薄。 随着模型能力提升，越来越多约束逻辑应该”卸载”给模型本身——但每升一档模型能力，都需要重新审视 harness 边界。强 ≠ 复杂；成熟的 harness 是少而精。

3.5.5 2026 主流 LLM 横向对照表

选模型不能只看 leaderboard，要综合 能力 / context / 价格 / 速度 / 多模态 / 部署方式。下面是 2026-04-05 月主流模型对照（数字会变，方法论不变）。

闭源旗舰（高质量）

开源旗舰（性价比）

关键洞察

1. 2026 reasoning 已商品化：Kimi K2 / Qwen3 / GLM-5 给 R1 级别推理，价格 $0.40-2/M——“为质量付十倍” 论点失效
2. Sonnet 4.6 是性价比锚点：$3/$15 + 90% cache 折扣 = 大多数场景最佳综合
3. Llama 4 Scout 10M context 把”超长文档塞进单次推理”重新变可行（其他还是 128K-1M）
4. GPT-5 mini 0.25/2 把高级模型的便宜变体推到 GPT-3.5 价格，做高 QPS 任务首选

实战路由策略：节 85% 成本 still 几乎无质量损失

真实数据（来自一家生产部署）：把 70% 流量路由到 DeepSeek V4-Flash、25% 到 Claude Sonnet 4.6、5% 到 Claude Opus 4.7，整体性能与全用 frontier 模型不可区分，成本约 15%。

def route_by_complexity(query, user_context):
    # 简单分类先用便宜模型
    classifier_result = haiku_or_deepseek_flash.invoke(
        f"分类下面 query 的难度：simple / medium / hard\n{query}"
    )
    difficulty = classifier_result.strip()
    if difficulty == "simple":
        return deepseek_v4_flash       # 70% 流量
    elif difficulty == "medium":
        return claude_sonnet_4_6       # 25%
    else:
        return claude_opus_4_7         # 5%

LiteLLM / Portkey / OpenRouter 都内置 cost-based 或 quality-based routing。

3.5.6 Cost 优化系统化：8 个杠杆按 ROI 排序

LLM cost 优化不是单一技术，是 8 个杠杆的组合。按 ROI 排序：

真实组合案例：从 $30K/月 降到 $5K/月

某 SaaS 公司跑 10 万 daily active user 的 AI 客服：

原始：纯 Claude Opus 4.7
       Cost: ~$30,000/月
       p95 latency: 8s

优化 1：加 Prompt Caching（system + tools + RAG 知识库）
       Cost: $30K → $12K/月（-60%）
       p95 latency: 8s → 5.5s

优化 2：加 Model Routing（70% DeepSeek-V4-Flash, 25% Sonnet, 5% Opus）
       Cost: $12K → $5K/月（-58%）
       p95 latency: 5.5s → 4s
       Quality（user satisfaction）: 4.6 → 4.5（几乎无感）

优化 3：加 Semantic Cache（30% 命中）
       Cost: $5K → $3.5K/月（-30%）
       p95 latency: 4s → 1.2s（cache 命中）/ 4s（miss）

总: $30K → $3.5K（-88%），用户体验反而更好

反模式：不该做的”省钱”

• ❌ 降 max_tokens 太狠：模型截断 → 用户重试 → 总 cost 反而高
• ❌ 盲目用最便宜模型：质量崩 → 用户流失 → 业务 cost 远大于 LLM cost
• ❌ 关掉 thinking model 推理预算：复杂任务做错 → 后续补救 cost 高
• ❌ 长 prompt 频繁修改：cache 命中率低 → 缓存白写

3.6 Recommendations：三类典型场景的选型清单

场景一：个人学习 / 周末项目

目标：理解原理 + 跑通端到端 预算：API 几美元，硬件用现有

直接抄 LangChain / LlamaIndex 官方 cookbook 改改就跑。

场景二：创业 MVP / 小团队产品

目标：尽快上线 + 可演进 预算：每月几百 USD

总成本：服务器 ~$100/月 + LLM 按量。

场景三：企业生产 / 合规敏感

目标：稳定、可观测、合规、可审计 预算：六位数月度

通用建议：无论哪种场景，从 day 1 就接观测。Langfuse 接入零成本，没接的代价是 6 个月后做不出任何”为什么这个 query 失败了”的根因分析。

3.7 Limitations & Caveats

1. 行业仍在快速演化：本系列截至 2026-05-01。MCP、Agent Skills、A2A 协议、推理服务器都在数月级别迭代，6 个月后细节可能过时
2. 基准数据有作弊空间：MTEB、RULER、reranker ELO、SWE-bench / GAIA 都存在 cherry-pick 风险（详见 agent-engineering.md §7.3 警告）。生产前必须在自己业务数据上重测
3. “驾驭工程”作为术语仍年轻：2026-02 才被正式命名，社区共识还在形成。本文采用 Hashimoto / Augment Code / Atlan / Adnan Masood 等 ≥4 个独立来源都引用的描述，但术语边界仍可能漂移
4. 未覆盖：模型推理数学（attention 推导、loss 函数）、具体业务案例 ROI、提示词攻击 / 越狱的详细技术目录、监管细节（EU AI Act 全文）
5. 评分有主观成分：选型表里的”推荐”基于公开评测 + 社区共识 + 笔者实战偏好，不构成对所有场景的最优解
6. 付费 vs 开源：本系列偏向开源方案介绍。商业 SaaS 在很多场景的”零运维”价值未被充分体现
7. 中文场景特殊性：中文 embedding / RAG / 模型选型与英文场景有差异。本系列给出的推荐已尽量考虑中文场景，但具体业务（金融 / 法律 / 医疗）的中文 NLP 仍需领域 fine-tune
8. 棕地（legacy）项目仍是开放问题：目前所有 harness 成功案例（OpenAI 百万行实验、Augment Code、Anthropic 长任务）都是绿地项目。如何为十年历史的遗留代码库引入 harness 而不被 lint 警报淹没、不被存量技术债拖死——这是 2026 年最大的未解难题。L4 自治循环在 legacy 代码上的可行性尚无公开实证
9. 更好的模型让 harness 更重要，而非更不重要：常见的误解是模型变强 harness 就可以放松。多家团队的复测正好相反——模型能触达的复杂度越高，对 harness 的要求也越严格。Carlini 的观察：Opus 4.5 能产出能用的编译器、Opus 4.6 能编译 Linux 内核——但每个能力级别都需要重新设计与之匹配的 harness。Manus 团队半年重写 5 次 harness，每次方向都是简化。强 ≠ 复杂；薄 ≠ 弱
10. AI 编码并未取代软件工程的工艺，反而抬高了工艺门槛：当 agent 写代码的速度成为非瓶颈，约束设计、反馈回路、架构纪律就成了团队产出质量的全部决定因素。在 L0-L1 的团队里，工程师写得多的人产出多；在 L3-L4 的团队里，harness 设计水平决定一切

3.8 GitHub 实战资源（驾驭层专题）

按支撑性基础设施 7 类分类的开源仓库与官方文档（再次强调：这是工具选型清单，不是 harness 方法论的拆法；方法论见 §3.3.0 两条法则 + 四大支柱）：

工具集成 / MCP

• modelcontextprotocol/servers — 官方 MCP server 集合（GitHub / Slack / Postgres / Filesystem 等几十个）
• modelcontextprotocol/python-sdk — Python SDK
• modelcontextprotocol/typescript-sdk — TypeScript SDK
• punkpeye/awesome-mcp-servers — 社区 MCP server awesome list

沙箱

• e2b-dev/E2B — agent 用的安全代码沙箱（microVM）
• daytonaio/daytona — 开源 dev environment + agent sandbox
• firecracker-microvm/firecracker — AWS 出品的 microVM 内核

LLM 网关

• BerriAI/litellm — 100+ LLM 统一接口
• Portkey-AI/gateway — Portkey 开源版
• Helicone/helicone — Rust LLM 网关 + observability
• OpenRouter — 不开源但 SaaS 极成熟

推理服务器

• vllm-project/vllm — PagedAttention 主流
• sgl-project/sglang — RadixAttention，多轮 / agent 强
• LMCache/LMCache — 跨实例 KV cache 复用
• huggingface/text-generation-inference — TGI（已 maintenance）

可观测性

• langfuse/langfuse — MIT，6M+ 月安装
• Arize-ai/phoenix — RAG 可视化强项
• langchain-ai/langsmith-sdk — LangChain 原生
• comet-ml/opik — Comet 开源版

评估

• confident-ai/deepeval — 50+ 指标、pytest 集成
• explodinggradients/ragas — RAG 评估事实标准
• promptfoo/promptfoo — 红队 + CI gate
• openai/evals — OpenAI 官方框架
• microsoft/promptbench — Microsoft 出品的 prompt 评估

护栏

• NVIDIA-NeMo/Guardrails — Colang DSL，5 类 rails
• guardrails-ai/guardrails — Pydantic 风格 validator
• leondz/garak — LLM 红队 / 漏洞扫描

综合 / awesome 入口

• Hannibal046/Awesome-LLM — LLM 总入口
• mlabonne/llm-course — LLM 课程合集，分基础 / fine-tune / 部署三条路径
• microsoft/generative-ai-for-beginners — 18 节生成式 AI 入门
• SylphAI-Inc/LLM-engineer-handbook — 工程师手册，覆盖各栈
• Shubhamsaboo/awesome-llm-apps — 100+ LLM 应用源码

驾驭工程文章 / 报告

• Anthropic Building Effective AI Agents（必读，03 §3.4 详解）
• Dive into Claude Code (arXiv 2604.14228) — Claude Code 设计空间分析
• Hashimoto / Augment Code Harness Engineering for AI Coding Agents

3.9 附录：相关 LLM 应用基础设施栈（不是 harness 工程）

重要框架订正：原版本把这 4 类（LLM 网关 / 推理服务器 / 可观测性 / 评估）混在 §3.3 “驾驭层组件”里——这是不准确的。它们是任意生产 LLM 应用都需要的支撑设施品类，不是 harness 工程的方法论特征。

把它们和 harness 工程放在一起讲只是因为读者建栈时常常一并选型；但读者请明确：

• 真正的 harness 工程内容：§3.3.0（两条法则 + 四大支柱）+ §3.3.1-§3.9.1（MCP / 沙箱 / 护栏 — 这 3 个是 harness 强约束的直接实现）+ §3.4.6（成熟度模型）+ §3.5.4.5（熵管理）
• 本附录的 4 类：LLM 应用的通用基础设施品类，跟”驾驭工程”在概念上是平行的，不是它的子集

保留在章里只为读者一站式查询；如果你在做严格意义上的 harness 工程方法论，本附录可跳过。

3.9.1 LLM 网关（LLM Gateway）

把”调用 LLM”从你的业务代码里抽离到独立的网关层，统一处理：路由、fallback、缓存、限流、计费、观测、密钥管理。2026 年主流方案 [37][38]：

关键能力：

• 多 provider 路由：根据成本 / 延迟 / 模型能力动态选 provider。GPT-4 失败 fallback 到 Claude 再 fallback 到 Llama
• 语义缓存：Portkey 和 Cloudflare 的杀手锏——不是字面匹配，而是”语义相似的 query 复用 cached response”。客服 / 知识库场景能做到 60%+ 缓存命中
• 熔断：Helicone 的”健康感知路由 + circuit breaking”在 provider 故障时自动隔离故障 endpoint
• 统一计费 + 配额：按 user_id / org_id 配额、防止恶意用户烧光额度
• 密钥管理：业务代码不接触 API key，全在网关里

注意 [37]：2026 年 LLM proxy 生态出过两件大事——Helicone 被收购、LiteLLM 被检测出依赖供应链问题。“在生产环境运行第三方 proxy”本身是个安全决策，企业级建议自托管 + 锁版本。

3.9.2 推理服务器（Inference Server）

如果你自部署模型（开源 7B-70B 或自家训的），推理服务器决定了吞吐和成本。2026 年的状态 [39][40]：

• TGI（Text Generation Inference，HuggingFace）：2025 年 12 月起进入 maintenance mode。HF 官方推荐新部署用 vLLM 或 SGLang
• vLLM（UC Berkeley Sky Lab）：核心创新是 PagedAttention [10]，把 KV cache 切成 16 token 一页，用类似操作系统虚拟内存的方式管理，显存碎片<4%。这让单卡能跑的并发数几倍提升。生态最广。支持 prefix caching（自动检测共享前缀复用 KV）、speculative decoding（小模型先猜大模型再校验，1.3-2× 加速，acceptance rate≥0.7 时）
• SGLang（LMSYS）：核心创新是 RadixAttention [11]——用 radix tree 数据结构自动发现并复用 KV cache，不需要手动配置 prefix caching。在多轮对话和 agent 场景（请求间共享动态上下文）比 vLLM 快 10-20%；在 prefix-heavy workload 上比基线快最多 6.4×。小模型场景（7B-13B）SGLang 比 vLLM 高 ~29% 吞吐；70B 规模差异收窄到 3-5%
• NVIDIA Triton Inference Server：传统选择，多模态 / 多模型混跑场景仍有人用，但纯 LLM 推理已经没什么优势
• LMCache（2025 提出）：作为独立的 KV cache 层，可以跨不同的推理服务器实例共享 cache。企业多副本部署时能再节省 30-50% 显存

选型经验：纯文本 LLM 推理 → SGLang（多轮 / agent 场景）或 vLLM（通用 / 简单 single-turn）；多模态混跑 → vLLM 或 Triton。

3.9.3 可观测性（Observability）

3.9.3.1 LLM 可观测性 vs 传统 APM

LLM 应用的 trace 比传统服务复杂得多——一次请求可能涉及多次 LLM 调用、多次工具调用、多次检索、多次 reranker、多个 sub-agent。和传统 APM 的关键差异：

3.9.3.2 三件套：Trace / Metrics / Eval

• Trace：一次 user request 的完整调用链。包括 LLM call 嵌套 tool call 嵌套 sub-agent call
• Metrics：聚合指标（QPS / 延迟分布 / token 使用 / cost 趋势 / 错误率）
• Eval：质量信号（faithfulness / accuracy / 用户反馈），与 trace 关联

3.9.3.3 OpenTelemetry GenAI 语义约定（2026 标准）

OpenTelemetry GenAI SIG 自 2024-04 起制定 GenAI 语义约定。2026 年虽仍在 experimental status，但 Datadog v1.37 起原生支持，Grafana Loki / OpenLLMetry 跟进——已是事实标准。核心 attribute namespace：

gen_ai.system                     # "openai" / "anthropic" / "google"
gen_ai.operation.name             # "chat" / "completion" / "embedding"
gen_ai.request.model              # "gpt-4o" / "claude-sonnet-4-6"
gen_ai.request.temperature        # 0.7
gen_ai.request.max_tokens         # 4096
gen_ai.response.id                # "msg_01ABC..."
gen_ai.response.model             # 实际响应模型（可能 != request.model 因 fallback）
gen_ai.response.finish_reasons    # ["stop"] / ["tool_calls"] / ["length"]
gen_ai.usage.input_tokens         # 1234
gen_ai.usage.output_tokens        # 567
gen_ai.usage.total_tokens         # 1801

# Agent 专属
gen_ai.agent.id                   # 唯一 agent id
gen_ai.agent.name                 # "researcher" / "writer"
gen_ai.tool.name                  # "web_search"
gen_ai.tool.call.id               # tool call id
gen_ai.tool.type                  # "function" / "mcp"

OTel 层面的 trace 自动捕获后，可以接 Datadog / Grafana / Jaeger / Honeycomb 任意后端。接入零侵入（只要 LLM SDK 支持 OTel）。

3.9.3.4 必采的 11 项关键 metrics

任何生产 LLM 应用都应监控（按重要性排序）：

3.9.3.5 Trace 设计：3 层 span 结构

生产 agent 通常 nested span 三层：

[span: agent_session]              ← 最外层，用户一次会话
├─ [span: agent_step]              ← agent 一次思考-行动循环
│  ├─ [span: llm_call]             ← LLM 推理
│  │   ├─ gen_ai.* attributes
│  │   └─ event: prompt / completion
│  ├─ [span: tool_call]            ← 工具调用
│  │   ├─ gen_ai.tool.name
│  │   └─ event: tool_input / tool_output
│  └─ [span: rag_retrieve]         ← RAG
│      ├─ retrieval.k
│      ├─ retrieval.score_distribution
│      └─ retrieval.documents
└─ [span: agent_step]              ← 第二步
   └─ ...

每个 span 都打上：trace_id（贯穿整个会话）、user_id、session_id、agent_id、cost、tokens。

3.9.3.6 采样策略：不能 100% 全采

100% 采样 = 存储与成本爆炸。三种主流策略：

推荐 tail sampling 配置：

• 100% 采样：错误、长尾延迟（>p95 × 2）、cost outlier (>$0.10/call)、Loop of Death 触发
• 10% 采样：成功的常规请求
• 1% 采样：cache 命中的 trivial 请求
• 100% 采样：开发者手动标记 debug=true 的

3.9.3.7 主流平台对比

实战 [33][34]：

• 想要功能完整 + 自托管 → Langfuse
• 已用 LangChain → LangSmith（自动集成）
• 不想改 SDK，只想接个 proxy → Helicone
• 重点是 RAG → Arize Phoenix（retrieval drift 可视化是它的看家本领）
• 已用 Datadog → Datadog LLM Obs（GenAI 语义约定原生）
• 想要 vendor-neutral → OpenLLMetry + 任意 OTel 后端

很多团队最后落到”两个工具组合”：一个 OSS 平台（Langfuse / Phoenix）做开发与 dashboard，一个 proxy 网关（Helicone）做生产流量观测，底层都跟 OpenTelemetry GenAI 标准对齐。

3.9.3.8 隐私与 PII：trace 落盘前必做

LLM trace 含 prompt 和 completion 全文，可能含用户 PII / 商业秘密。必须在落盘前做 redaction：

# Langfuse 配置 mask 函数
from langfuse.decorators import langfuse_context

def mask_pii(data):
    """自定义 mask：手机号 / 身份证 / 邮箱 / 信用卡"""
    import re
    text = str(data)
    text = re.sub(r'\b1[3-9]\d{9}\b', '[PHONE]', text)
    text = re.sub(r'\b[\w\.-]+@[\w\.-]+\.\w+\b', '[EMAIL]', text)
    text = re.sub(r'\b\d{17}[\dXx]\b', '[ID]', text)
    text = re.sub(r'\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b', '[CARD]', text)
    return text

langfuse_context.update_current_observation(input=mask_pii(prompt))

注意：mask 必须在 SDK 入栈时做，不能依赖后端事后清洗——一旦 raw 数据离开应用进程，合规风险已经发生。

3.9.4 评估（Evaluation）

3.9.4.1 评估的两个轴 + 三种来源

LLM 应用没有传统单元测试那种”输入 X 必须输出 Y”的硬约束。评估按时机分两类 [35]：

• 离线评估（Offline Eval）：跑一个固定的 dataset，用 metric / LLM-as-judge / 人工打分
• 在线评估（Online Eval）：在生产流量里抽样评分，监控质量漂移

按评分来源分三类：

2026 年生产实践基本是三层组合：rule-based 在 CI 里做 sanity check（每次跑），LLM-as-Judge 在 PR 之前做大批量评估（每 PR 跑），human label 维护一个小但精的黄金集（每月校准）。

3.9.4.2 LLM-as-Judge：为什么这是核心范式

「让另一个 LLM 来评判这个 LLM 的输出」听起来像左脚踩右脚——但 2024 起被证明对很多任务比 BLEU/ROUGE 等传统 metric 准 50%+。原因：

• 能评估风格 / 语气 / 礼貌度等无法用 metric 表达的维度
• 能识别改写式正确答案（同义不同字）
• 能给出带理由的 chain-of-thought 评判，方便 debug
• 可按业务 rubric 自定义维度（“是否符合公司 tone”、“是否引用 source”）

但有 3 大著名 bias，必须治理。

3.9.4.3 LLM-as-Judge 三大 Bias 与缓解

附加 bias：

• Sentiment bias：偏积极语气
• Fallacy oversight：忽略推理链中的逻辑错误
• Refusal bias：把”礼貌拒答”打高分

2026 年研究（arXiv 2604.23178）系统性评估了多种缓解策略，结论：single judge 加 CoT prompt + counterfactual swap 是性价比最优组合；多 judge majority vote 减 30-40% bias 但成本 3-5×，仅用于高风险决策。

3.9.4.4 LLM-as-Judge 标准 Prompt 模板

不同评估范式的 prompt 写法：

Pointwise scoring（单条打分）：

你是一名严格的评审专家。请按下面 rubric 给回答打分。

# Rubric（1-4 量表）
4 = 完全准确、清晰、相关
3 = 大体准确，有小瑕疵
2 = 部分错误或不完整
1 = 严重错误或不相关

# 注意
- 不要因为回答更长就给更高分
- 仅评估准确性、清晰性、相关性
- 必须先思考再打分

# 问题
{question}

# 回答
{answer}

请按下面 JSON 格式：
{
  "reasoning": "...先逐步分析...",
  "score": 1-4,
  "issues": ["列出所有问题"]
}

Pairwise comparison（A vs B 比较）+ Position-bias mitigation：

def pairwise_judge_with_swap(judge_llm, question, answer_a, answer_b):
    # 跑两次，A/B 顺序交换
    result_ab = judge_llm.invoke(pairwise_prompt(question, answer_a, answer_b))
    result_ba = judge_llm.invoke(pairwise_prompt(question, answer_b, answer_a))

    # 只算"两次都同意"的 win
    win_ab = parse_winner(result_ab)  # 'A' or 'B' or 'tie'
    win_ba = parse_winner(result_ba)  # 注意 BA 的 'A' 实际是原 B

    if win_ab == 'A' and win_ba == 'B':
        return 'A_wins'   # 一致：A 真的更好
    elif win_ab == 'B' and win_ba == 'A':
        return 'B_wins'   # 一致：B 真的更好
    else:
        return 'inconsistent'   # 位置敏感，等价于 tie

3.9.4.5 Judge 模型的 4 条选型铁律

1. 判官必须强于被测：用 Haiku 评 Opus 输出 = 灾难。一般跨档：被测 GPT-4o → judge 用 Claude Opus 4.7 / GPT-5
2. 跨家族：评 Claude 用 GPT，反之亦然，规避 self-preference
3. 温度低：judge 必须 temperature=0（甚至 -1 thinking 模式），保证可复现
4. CoT 提示：让 judge 先 reasoning 再给 score，准确率高 15-25%

3.9.4.6 多 Judge 合议（Ensemble Judges）

高风险决策（医疗 / 法律 / 招聘）应该用多 judge 合议：

def ensemble_judge(question, answer, rubric):
    judges = [
        ("gpt-5", openai_judge),
        ("claude-opus-4-7", anthropic_judge),
        ("gemini-3-pro", google_judge),
    ]
    scores = []
    for name, judge in judges:
        result = judge(question, answer, rubric)
        scores.append({"judge": name, "score": result.score, "reasoning": result.reasoning})

    # 三种合议策略
    # 1. Majority vote（推荐）
    final = Counter(s["score"] for s in scores).most_common(1)[0][0]

    # 2. Average（仅当 score 是数值）
    # final = sum(s["score"] for s in scores) / len(scores)

    # 3. Strict（任一 judge 给低分就 fail）
    # final = min(s["score"] for s in scores)

    # 同时返回所有 judge 的 reasoning，方便 debug
    return {"final": final, "judges": scores, "agreement": calc_agreement(scores)}

经验：如果三个 judge 不一致（agreement < 0.6），升级到人工而不是用平均值搪塞。

3.9.4.7 Human Calibration：5-10% 是底线

没有人工校准的 LLM-as-Judge 是个未校准的工具。一定要：

• 黄金集（Golden Set）：50-200 个高质量人工标注样本，每月跑一次
• 持续 spot-check：生产流量 5-10% 抽样人工 review
• Judge agreement metric：定期计算 LLM-judge 与人工的 Pearson / Cohen’s kappa

def measure_judge_quality(judge_fn, golden_set):
    """衡量 LLM judge 与人工的一致性"""
    judge_scores = [judge_fn(item.question, item.answer) for item in golden_set]
    human_scores = [item.human_score for item in golden_set]

    pearson = scipy.stats.pearsonr(judge_scores, human_scores)
    kappa = sklearn.metrics.cohen_kappa_score(judge_scores, human_scores)

    return {
        "pearson": pearson.statistic,    # > 0.7 较好
        "kappa": kappa,                  # > 0.6 较好
        "needs_recalibration": kappa < 0.5,
    }

3.9.4.8 RAGAS：RAG 专属指标公式

RAG 评估的事实标准是 RAGAS 的 4 个核心指标（每个都用 LLM-as-judge 实现）：

实战阈值：4 个指标都 ≥ 0.7 算合格生产。Faithfulness < 0.7 = 模型在编造；Context Recall < 0.7 = 检索召回不够。

3.9.4.9 在线 Eval：监控质量漂移

线下评估好不代表线上稳定。Production 必须生产流量持续抽样评估：

@observe()  # Langfuse
def production_handler(query, user_id):
    answer = rag_chain.invoke(query)

    # 5% 流量异步评估
    if hash(user_id) % 100 < 5:
        asyncio.create_task(async_evaluate(query, answer, user_id))

    return answer

async def async_evaluate(query, answer, user_id):
    score = await llm_judge(query, answer, rubric=production_rubric)
    metrics.gauge("answer_quality", score, tags={"model": "claude-sonnet"})

    # 漂移告警
    if score < 0.6:
        alerts.send(f"Low quality on user={user_id}: score={score}")

漂移（Drift）的 4 种类型与检测方法：

A/B 在线评估的统计基础：

# 决定要多少样本才能检测出 X% 的差异
from statsmodels.stats.power import NormalIndPower
power_calc = NormalIndPower()

n_per_arm = power_calc.solve_power(
    effect_size=0.1,   # 想检测的最小差异（小=0.2, 中=0.5, 大=0.8）
    alpha=0.05,        # Type I error
    power=0.80,        # Type II error tolerance（1-β）
)
# 结果：要 ~1568 / arm 才能稳定检测 effect size 0.1 的差异

A/B 实战清单：

1. 预先定义主指标 + 护栏指标：主 = 答案质量；护栏 = 延迟 / 成本 / 拒答率（防止”质量上升但成本翻倍”上线）
2. CUPED / 协变量回归：减小方差，缩短实验周期 30-50%
3. Sequential testing（mSPRT）：可以”边跑边看”而不破坏统计有效性，传统 t-test peeking 会爆假阳
4. Auto-rollback 触发：护栏指标越界（如 p99 latency > 5s 或 quality_score < baseline-2σ）持续 10 分钟 → 自动回滚
5. Holdout 永久对照：保留 1-5% 流量永远在 baseline，用来量化”如果我没改”的 counterfactual

3.9.4.10 主流框架对比与组合

实战 [35]：「你几乎一定需要两个工具——一个轻量框架（DeepEval / RAGAS / Promptfoo）做 CI/CD gating，一个平台（Braintrust / LangSmith / Arize）做人工标注、回归追踪、stakeholder dashboard。」

Agent 专属评估基准（SWE-bench / GAIA / WebArena / OSWorld）见 agent-engineering.md §7，及其重要警告：8 个主流基准全部被证实可被 hack 出近完美分数。

Bibliography（系列总参考文献）

论文 / 学术资源

• [1] Vaswani, A. et al. (2017). Attention Is All You Need. NeurIPS. https://arxiv.org/abs/1706.03762
• [2] Liu, N. F. et al. (2024). Lost in the Middle: How Language Models Use Long Contexts. TACL.
• [3] Madaan, A. et al. (2023). Self-Refine: Iterative Refinement with Self-Feedback. NeurIPS.
• [4] Yao, S. et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models. ICLR 2023.
• [12] Hsieh, C. et al. (2024). RULER: What’s the Real Context Size of Your Long-Context Language Models? https://arxiv.org/abs/2404.06654
• [16] Asai, A. et al. (2023). Self-RAG: Learning to Retrieve, Generate, and Critique through Self-Reflection.
• [18] Packer, C. et al. (2023). MemGPT: Towards LLMs as Operating Systems.
• [19] Mem0 Team (2025). Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory. https://arxiv.org/abs/2504.19413
• [26] Hu, E. et al. (2021). LoRA: Low-Rank Adaptation of Large Language Models.
• [27] Dettmers, T. et al. (2023). QLoRA: Efficient Finetuning of Quantized LLMs.
• [51] Shinn, N. et al. (2023). Reflexion: Language Agents with Verbal Reinforcement Learning. NeurIPS. https://arxiv.org/abs/2303.11366
• arXiv. Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems (2026). https://arxiv.org/html/2604.14228v1
• arXiv. AI Agent Systems: Architectures, Applications, and Evaluation (2026). https://arxiv.org/html/2601.01743v1

业界文章 / 官方博客

• [5] Karpathy, A. Software Is Changing (Again). YC AI School talk.
• [6] Anthropic. Effective Context Engineering for AI Agents. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• [7] LangChain. Context Engineering for Agents. https://www.langchain.com/blog/context-engineering-for-agents
• [8] Augment Code (2026). Harness Engineering for AI Coding Agents. https://www.augmentcode.com/guides/harness-engineering-ai-coding-agents
• [9] Wikipedia. Model Context Protocol. https://en.wikipedia.org/wiki/Model_Context_Protocol
• [10] vLLM Blog (2025). Inside vLLM: Anatomy of a High-Throughput LLM Inference System.
• [11] Runpod Blog. When to Choose SGLang Over vLLM.
• [21] Anthropic Memory Tool docs.
• [22] Raschka, S. State of LLMs 2025. https://magazine.sebastianraschka.com/p/state-of-llms-2025
• [23] llm-stats. Post-Training in 2026: GRPO, DAPO, RLVR & Beyond. https://llm-stats.com/blog/research/post-training-techniques-2026
• [24] HuggingFace Blog. Guide to RL Post-Training: PPO, DPO, GRPO.
• [25] Introl. Fine-Tuning Infrastructure: LoRA, QLoRA, PEFT at Scale.
• [28] PromptingGuide.ai. https://www.promptingguide.ai
• [29] Pillitteri, P. Prompt Engineering 2026: Frameworks That Actually Work.
• [30] BrightCoding. Prompt Engineering Guide.
• [31] Atlan. What Is Harness Engineering AI? The Definitive 2026 Guide. https://atlan.com/know/what-is-harness-engineering/
• [32] Masood, A. (2026). Agent Harness Engineering — The Rise of the AI Control Plane. Medium.
• [33] Spheron Blog. LLM Observability on GPU Cloud (2026).
• [34] Confident AI. Top 10 LLM Observability Tools to Evaluate & Monitor AI in 2026.
• [35] Confident AI. Top 7 LLM Evaluation Tools in 2026.
• [36] NVIDIA. NeMo Guardrails Documentation. https://docs.nvidia.com/nemo/guardrails/latest/index.html
• [37] Helicone Blog. Top 5 LLM Gateways.
• [38] PkgPulse. Portkey vs LiteLLM vs OpenRouter: LLM Gateway 2026.
• [39] PreMAI Blog. LLM Inference Servers Compared: vLLM vs TGI vs SGLang vs Triton (2026).
• [40] Runpod Blog. SGLang vs vLLM.
• [41] Tianpan. Long-Context Models vs RAG: When the 1M-Token Window Is the Wrong Tool.
• [42] BAAI. BGE-M3 model card. https://huggingface.co/BAAI/bge-m3
• [43] Squirro / 多源. RAG in 2026: Bridging Knowledge and Generative AI.
• [44] Hashimoto, M. (2026-02). My AI Adoption Journey — Step 5 Engineer the Harness. https://mitchellh.com/writing/my-ai-adoption-journey（“harness engineering” 这个术语的命名出处 verbatim）
• [45] Anthropic Engineering. Effective Harnesses for Long-Running Agents. https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents（Verifier ability ↔︎ success rate 实证定律 + Initializer/Coding Agent 双角色范式 + git/progress 文件 memory bridge）
• [46] Anthropic Research (2024-12). Building Effective Agents. https://www.anthropic.com/research/building-effective-agents（6 大 agentic pattern，含 evaluator-optimizer / orchestrator-workers / routing 等）
• [47] OpenAI (2026). Harness Engineering: Leveraging Codex in an Agent-First World. https://openai.com/index/harness-engineering/（OpenAI 内部产品实验：5 个月零行手写代码；提出 taste invariants 与依赖单向流动；金句 “Humans steer. Agents execute.” 与 “Agent = Model + Harness”）
• [49] Anthropic. Claude Code Documentation: Permissions / Sandboxing / Hooks. https://code.claude.com/docs/en/permissions, https://code.claude.com/docs/en/sandboxing, https://code.claude.com/docs/en/hooks-guide（deny→ask→allow 三段优先级 + OS-level Seatbelt/bubblewrap 沙箱 + PreToolUse exit code 2 闸门）
• [50] Cognition. Introducing Devin: The First AI Software Engineer. https://cognition.ai/blog/introducing-devin（一次性 VM per task 的强约束实现）
• [52] Anthropic Engineering. How We Built Our Multi-Agent Research System. https://www.anthropic.com/engineering/built-multi-agent-research-system（Adaptability × deterministic safeguards：retry / checkpoint / resume）

Agent 专题（详见 agent-engineering.md Bibliography）

Agent 范式、框架、benchmark、产品案例、失败模式、安全权限的完整参考文献见 03 章节末尾，本处不重复。

Methodology Appendix

调研设计

• Skill：deep-research v2.3.1（199-bio 版）
• Mode：ultradeep（用户 explicit “越全越好”，触发 8+ 阶段最深档）
• Search provider：内置 WebSearch（多供应商 search-cli 未配置 key，回退）
• 检索路数：26 路（v2 在 v1 基础上新增 8 路 Agent 专题）

26 路检索清单

v1 第一批（8 路）： 1. prompt engineering 2026 best practices Anthropic OpenAI 2. context engineering definition Karpathy Anthropic 3. harness engineering LLM agent infrastructure Karpathy 4. transformer architecture attention mechanism scaling laws 5. RAG state of the art 2026 GraphRAG Agentic RAG Self-RAG CRAG 6. vector database comparison 2026 Pinecone Weaviate Qdrant Milvus pgvector 7. embedding models 2026 BGE Cohere Voyage Jina OpenAI MTEB 8. LLM memory systems MemGPT Letta mem0 Zep Anthropic memory tool

v1 第二批（8 路）： 9. RAG reranker 2026 Cohere rerank BGE cross-encoder ColBERT hybrid search 10. long context vs RAG 2026 1M tokens lost in the middle needle haystack RULER 11. MCP Model Context Protocol A2A agent to agent function calling 12. LLM observability LangSmith Langfuse Helicone Arize Phoenix 13. LLM evaluation 2026 LLM-as-judge RAGAS DeepEval Promptfoo Braintrust 14. LLM guardrails NeMo Guardrails AI 2026 jailbreak prevention prompt injection 15. LLM gateway LiteLLM Portkey OpenRouter Helicone 2026 routing fallback 16. vLLM SGLang TGI inference server 2026 prompt caching speculative decoding KV cache

v1 第三批（2 路）： 17. LLM training pretraining post-training SFT DPO GRPO RLHF RLAIF 2026 18. LoRA QLoRA PEFT fine-tuning 2026 vs full fine-tune distillation

v2 新增 Agent 第四批（8 路）： 19. AI Agent definition architecture 2026 perception planning memory action framework 20. LangGraph AutoGen CrewAI OpenAI Agents SDK Smolagents Mastra Pydantic AI 2026 comparison 21. multi-agent system 2026 hierarchical swarm orchestration patterns supervisor 22. agent benchmark 2026 AgentBench GAIA SWE-bench WebArena OSWorld leaderboard 23. coding agent 2026 Claude Code Cursor Devin Manus GitHub Copilot Workspace Aider 24. computer use agent 2026 Anthropic Computer Use OpenAI Operator browser agent 25. autonomous agent failure modes infinite loop cost control hallucination 2026 26. AI agent safety permission model human in the loop sandbox 2026

Phase 4 TRIANGULATE — 跨多源验证（节选）

所有进入正文的关键事实都至少有 2 个独立来源支持：

Phase 6 CRITIQUE — 红队复核

• 怀疑派：是否漏了重要话题？v2 已新增 Agent 专题 8 路检索，覆盖范式 / 框架 / 多 agent / benchmark / 产品 / failure mode / safety。剩余可能遗漏：多模态模型架构（CLIP / VIT），但本系列聚焦 LLM 应用工程而非模型架构演进，可接受
• 对抗评审：是否过度简化？驾驭工程章节支撑设施 7 类每个 ~500-800 字，确有简化；本系列目标是导引图谱而非每组件深扒，可接受。每组件给了 2-3 个公开来源供读者深挖。框架订正：v3 修订承认”7 大组件”是不恰当合成命名，引入 4 支柱（参考 OpenAI/Anthropic/Stripe 实践收敛）作为方法论功能层，并把 7 类组件明确降级为”支撑性基础设施”
• 实施工程师：选型清单是否可立即落地？三类场景都给了具体产品名 + 部署方式，且明确了”day 1 必接观测”等首要原则

Phase 8 PACKAGE

• 主报告：README.md + prompt-engineering.md + context-engineering.md + agent-engineering.md + harness-engineering.md
• 合并版（v1）：article.md（保留作历史参考）
• 元数据：run_manifest.json、sources.jsonl
• HTML / PDF：未生成（用户未要求 + WeasyPrint 未安装）

复现命令

ls -la ~/Documents/Prompt_Context_Harness_Engineering_Article_20260501/
wc -m ~/Documents/Prompt_Context_Harness_Engineering_Article_20260501/0[1-4]_*.md

章节交叉引用

• 想理解 prompt 在 harness 里如何被 evaluate / version → 本章 §3.9.3 + §3.9.4
• 想理解 context（RAG / 记忆）的具体技术 → context-engineering.md
• 想理解 Agent 的范式、框架、产品 → agent-engineering.md
• 想从最底层基础入手 → prompt-engineering.md

LLM 应用工程的四层演进 · 系列文档 · 调研日期 2026-05-01

术语速查表

答案中以 [术语] 标记的概念都可点击跳到本表对应条目并自动展开。本表按 10 个主题分组收录 60+ 高频术语，默认全部收起——遇到不熟的术语再展开看精要解释，避免被信息淹没。