268 lines
11 KiB
Markdown
268 lines
11 KiB
Markdown
---
|
||
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 延迟加载
|
||
|
||
所有原则都有对应代码实现，可直接学习。
|