---
id: "2026-03-23-agent-engineering-practices"
title: "你不知道的 Agent：原理、架构与工程实践"
source_url: "本地 PDF: /home/kang/apps/content-forge/你不知道的 Agent：原理、架构与工程实践.pdf"
platform: "technical-doc"
author: "未知"
author_url: null
published_at: "2026"
collected_at: "2026-03-23"
metrics:
  pages: 59
  sections: 10
  diagrams: 15+
  code_examples: 20+
viral_score: null
tags: ["agent", "llm", "engineering", "architecture", "openai", "context-engineering", "tool-design", "multi-agent", "evaluation", "security", "production"]
language: "zh-CN"
related_topics: []
analysis: |
  这是一份从原理到生产的完整 Agent 工程实践指南，作者在完成《你不知道的 Claude Code》后，针对 Agent 底层原理的系统梳理。

  文档质量极高，包含：
  - OpenAI 3 人 5 月 100 万行代码的真实案例
  - 完整的上下文工程方法论（分层、缓存、压缩）
  - 工具设计三代演进（API 封装 → ACI → Advanced Tool Use）
  - 多 Agent 组织模式（Director vs Orchestrator）
  - 两层可观测性架构（人工抽样 + LLM 自动评估）
  - 三层安全模型（沙箱 + 权限 + 审计）
  - OpenClaw 参考实现（五层解耦架构）

  为什么火（技术文档维度）：
  - 真实案例支撑：OpenAI 团队实践，10x 开发速度数据
  - 完整方法论：从原理到生产的完整路径
  - 可执行架构：15+ 架构图 + 20+ 代码示例
  - 踩坑经验：大量 "为什么" 和 "常见错误" 章节
  - 参考实现：OpenClaw 开源项目可直接学习
takeaways:
  - "Harness 比模型更关键 — 验收基线、执行边界、反馈信号、回退手段决定系统能否稳定运行"
  - "上下文分层是稳定性基础 — Always present 短而稳定，保护缓存命中率，节省 40-90% token 成本"
  - "工具对应 Agent 目标，不是 API 操作 — ACI 设计原则，一次搞定而非多步协调"
  - "任务状态要显式写出来 — 不留在工作记忆，写入 JSON 文件，支持跨 Session 续跑"
  - "协议先定，隔离先做，再谈协作 — 多 Agent 组织的正确顺序，避免幻觉互相放大"
  - "评测看 Transcript + Outcome — 不只看说了什么，还要看系统最后变成什么样"
  - "两层可观测性 — 人工抽样标注（慢、精准、设标准）+ LLM 自动评估（快、规模化、需校准）"
  - "事件流作为底座 — 发布一次，多路消费，主循环不变，下游随意扩展"
  - "三层安全模型 — 沙箱隔离 + 基于能力的权限系统 + 审计日志，防御 6 类攻击向量"
  - "OpenClaw 是可运行的参考实现 — 五层解耦，23+ 渠道适配，所有原则都有对应代码"
---

# 你不知道的 Agent：原理、架构与工程实践

## 文档概览

这是一份 59 页的 Agent 工程实践深度文档，覆盖从原理到生产部署的完整路径。

**10 个核心章节**：

1. **Agent Loop 基本运转方式** — 20 行代码实现 Perceive → Decide → Act → Feedback 循环
2. **Workflow vs Agent 本质区别** — 控制权在代码还是 LLM，7 维度对比表
3. **五种常见控制模式** — Prompt Chaining、Routing、Parallelization、Orchestrator-Workers、Evaluator-Optimizer
4. **为什么 Harness 比模型更关键** — 验收基线、执行边界、反馈信号、回退手段
5. **上下文工程决定稳定性** — 分层管理、Prompt Caching、压缩策略、Skills 延迟加载
6. **工具设计决定 Agent 能力** — ACI 原则、Tool Search、Programmatic Tool Calling、Tool Use Examples
7. **记忆系统设计** — 四层记忆（Context window、Skills、JSONL 历史、MEMORY.md）
8. **多 Agent 组织** — Director vs Orchestrator、JSONL 协议、Worktree 隔离、交叉验证
9. **Agent 评测方法** — Transcript + Outcome 双维度、两层可观测性、事件流架构
10. **安全与生产部署** — 三层安全模型、攻击向量防御、成本优化、OpenClaw 参考实现

## 最具价值的案例：OpenAI Agent 开发实践

**数据**：3 个工程师，5 个月，100 万行代码，近 1500 个 PR，10x 传统开发速度

**4 条关键工程决策**：

1. **Agent 看不到的内容等于不存在** — 知识必须存在于代码库本身，AGENTS.md 只保留约 100 行索引
2. **约束编码化而非文档化** — 架构分层靠自定义 Linter 机械强制，不靠人工 Review
3. **Agent 端到端自主完成任务** — 从验证、复现、修复、验证到开 PR、处理 Review、自主合并，全链路无人介入
4. **最小化合并阻力** — 测试偶发失败用重跑处理，高吞吐环境下等待人工审查成本高于修复小错误

**完整可观测性栈**：

```
APP → VECTOR → Victoria (Logs/Metrics/Traces)
    → LogQL/PromQL/TraceQL APIs → CODEX
```

Codex 通过三个查询接口主动验证修改是否生效，不需要等人告知错误。

## 可复用的架构模式

### 1. 上下文分层架构

```
Always present (常驻层)
  ↓ 身份定义、项目约定、绝对禁止项
  ↓ 保持短、硬、可执行
  ↓ 高缓存命中率，节省 40-90% 成本

On-demand (按需加载)
  ↓ Skills 和领域知识
  ↓ 描述符常驻，完整内容触发时注入
  ↓ 不破坏前缀稳定性

Runtime inject (运行时注入)
  ↓ 当前时间、渠道 ID、用户偏好
  ↓ 每轮按需拼入

Persisted memory (记忆层)
  ↓ 跨会话经验写入 MEMORY.md
  ↓ 需要时才读取

Never enters (系统层)
  ↓ Hooks 或代码规则处理确定性逻辑
  ↓ 完全不进上下文
```

### 2. 长任务跨 Session 续跑

```
Session 1: Initializer Agent (运行一次)
  ↓ 生成 feature-list.json (200+ features, all passes: false)
  ↓ 生成 init.sh (restart dev server)
  ↓ 初始 git commit (baseline)
  ↓ 生成 claude-progress.txt (progress tracker)
  ↓ 文件系统持久化

Session 2-N: Coding Agent (可重启)
  ↓ 读取 progress.txt + git log
  ↓ 定位当前任务
  ↓ 实现一个功能
  ↓ 运行测试，更新 passes
  ↓ 提交代码，退出
  ↓ 下一个 Session 继续

崩溃或上下文耗尽？
  → 重启 Session
  → 从文件 + git log 恢复现场
  → 继续执行

状态通过文件系统传递，不依赖上下文
每个 Session 无状态，文件是记忆
```

### 3. 多 Agent 组织架构

```
Main Agent (Orchestrator)
  ↓ 分解任务
  ↓ 通过 JSONL inbox 分派
  ↓ 只读取 summary，不看细节
  ↓
  ├─→ Sub-agent A (独立 messages[])
  │   ├─ .worktrees/agent-a (文件隔离)
  │   └─ 返回 summary
  │
  ├─→ Sub-agent B (独立 messages[])
  │   ├─ .worktrees/agent-b (文件隔离)
  │   └─ 返回 summary
  │
  └─→ Sub-agent C (独立 messages[])
      ├─ .worktrees/agent-c (文件隔离)
      └─ 返回 summary

.tasks/ (控制平面)
  ↓ 任务图、owner、blockedBy、status

.team/inbox/{agentId}.jsonl (协议层)
  ↓ request_id、from_agent、to_agent
  ↓ status: pending | approved | rejected
  ↓ append-only，崩溃可恢复

协议先定，隔离先做，再谈协作
主 Agent 看摘要，子 Agent 持有细节
```

### 4. 两层可观测性架构

```
Full trace stream (完整追踪流)
  ↓
  ├─→ Layer 1: Human sampling (人工抽样)
  │   ├─ 错误案例、长对话、负反馈
  │   ├─ 基于规则采样
  │   ├─ 人工标注失败原因
  │   └─ 生成校准数据集
  │       ↓
  │   慢、精准、设标准
  │
  └─→ Layer 2: LLM evaluator (LLM 自动评估)
      ├─ 全量覆盖、在线、自动化
      ├─ 对所有 Trace 打分
      ├─ 成本可控
      ├─ 漂移检测，用 Layer 1 重新校准
      └─ 聚合指标，规模化质量评分
          ↓
      快、可扩展、需校准

两层一起用：
  Layer 1 提供 ground truth
  Layer 2 提供规模化覆盖
  定期用 Layer 1 校准 Layer 2
```

## 可直接应用的工程原则

### 上下文工程

- **分层管理**：Always present（短而稳定）→ On-demand（Skills）→ Runtime（动态注入）→ Memory（跨会话）→ Never enters（Hooks）
- **Prompt Caching**：稳定的大系统提示比频繁变动的小提示成本更低（90% 折扣）
- **压缩保留优先级**：架构决策 > 已修改文件 > 验证状态 > TODO > 工具输出（只保留结论）
- **文件系统作为上下文接口**：工具写文件，Agent 读文件，开发者可直接查看

### 工具设计

- **ACI 原则**：工具对应 Agent 目标，不是 API 操作（create_script 而非 create_file + write_content + set_permissions）
- **Tool Search**：动态发现工具定义，上下文保留率 95%
- **Tool Use Examples**：每个工具附带 1-5 个实际调用示例，准确率从 72% 提升到 90%
- **结构化错误**：返回修正建议，不是通用字符串 "Error"

### 长任务管理

- **跨 Session 续跑**：Initializer Agent（生成 feature-list.json + progress.txt）+ Coding Agent（循环执行）
- **任务状态显式化**：写入 JSON 文件，不留在工作记忆
- **后台 I/O**：慢速 subprocess 放到后台线程，通过队列注入结果

### 多 Agent 组织

- **协议先定，隔离先做**：JSONL inbox + Worktree 隔离 + 任务图管理依赖
- **子 Agent 最小提示**：只给 Tooling/Workspace/Runtime，不带 Skills/Memory
- **交叉验证**：防止幻觉互相放大（conformity bias）

### 评测与追踪

- **Transcript + Outcome**：不只看说了什么，还要看系统最后变成什么样
- **两层可观测性**：人工抽样标注 + LLM 自动评估，两层一起用
- **事件流底座**：发布一次，多路消费，主循环不变
- **先修评测，再改 Agent**：评测出问题会给出失真信号

### 安全与生产

- **三层安全模型**：沙箱隔离 + 基于能力的权限系统 + 审计日志
- **6 类攻击向量**：Prompt injection、Tool chaining、Context poisoning、Resource exhaustion、Data exfiltration、Privilege escalation
- **生产检查清单**：环境隔离（P0）、权限控制（P0）、监控告警（P0）、回滚机制（P0）、事件响应（P0）

## 关联选题

这份文档可以拆解为多篇深度技术文章：

1. **OpenAI 如何用 Agent 写代码：3 人 5 月 100 万行的工程实践** — 真实案例 + 4 条工程决策 + 完整可观测性栈
2. **Agent 上下文工程实战：从分层设计到 Prompt Caching** — 节省 40-90% 成本的方法论
3. **工具设计三代演进：从 API 封装到 ACI** — 为什么工具对应目标而非操作
4. **长任务如何跨 Session 续跑：Initializer + Coding Agent 双角色模式** — 支持崩溃恢复的架构
5. **多 Agent 组织模式：Director vs Orchestrator** — 协议先定，隔离先做，再谈协作
6. **Agent 评测方法论：Transcript + Outcome 双维度** — 两层可观测性架构
7. **Agent 安全与生产部署：三层安全模型** — 6 类攻击向量的防御策略
8. **OpenClaw 架构拆解：五层解耦的参考实现** — 从原理到代码的完整路径

## 参考实现

**OpenClaw**：开源 Agent 系统，五层解耦架构
- Gateway：WebSocket 服务，统一路由
- Channel 适配器：23+ 渠道统一接口
- Agent 层：ReAct 循环、会话管理、记忆整合、主动调度
- 工具集：shell/fs/web/browser/MCP，按 ACI 原则设计
- 上下文+记忆：SOUL.md + MEMORY.md + Skills 延迟加载

所有原则都有对应代码实现，可直接学习。