From 7ca0d00164ab8c04411b9a77a64f4199aa2a00f4 Mon Sep 17 00:00:00 2001 From: lizikk Date: Mon, 23 Mar 2026 02:00:01 +0800 Subject: [PATCH] vault: auto-sync 2026-03-23 02:00 --- .../2026-03-23-agent-engineering-practices.md | 267 ++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 09-viral-examples/2026-03-23-agent-engineering-practices.md diff --git a/09-viral-examples/2026-03-23-agent-engineering-practices.md b/09-viral-examples/2026-03-23-agent-engineering-practices.md new file mode 100644 index 0000000..efd7aab --- /dev/null +++ b/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 延迟加载 + +所有原则都有对应代码实现，可直接学习。