vault: auto-sync 2026-03-23 02:00

09-viral-examples/2026-03-23-agent-engineering-practices.md

@@ -0,0 +1,267 @@
+---
+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 延迟加载
+
+所有原则都有对应代码实现，可直接学习。