zhukang/content-forge-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7ca0d00164
content-forge-vault/09-viral-examples/2026-03-23-agent-engineering-practices.md
lizikk 7ca0d00164 vault: auto-sync 2026-03-23 02:00
2026-03-23 02:00:01 +08:00

11 KiB
Raw Blame History

id title source_url platform author author_url published_at collected_at metrics viral_score tags language related_topics analysis takeaways
2026-03-23-agent-engineering-practices 你不知道的 Agent：原理、架构与工程实践 本地 PDF: /home/kang/apps/content-forge/你不知道的 Agent：原理、架构与工程实践.pdf technical-doc 未知 null 2026 2026-03-23
pages sections diagrams code_examples
59 10 15+ 20+
null
agent
llm
engineering
architecture
openai
context-engineering
tool-design
multi-agent
evaluation
security
production
zh-CN
这是一份从原理到生产的完整 Agent 工程实践指南，作者在完成《你不知道的 Claude Code》后，针对 Agent 底层原理的系统梳理。 文档质量极高，包含： - OpenAI 3 人 5 月 100 万行代码的真实案例 - 完整的上下文工程方法论（分层、缓存、压缩） - 工具设计三代演进（API 封装 → ACI → Advanced Tool Use） - 多 Agent 组织模式（Director vs Orchestrator） - 两层可观测性架构（人工抽样 + LLM 自动评估） - 三层安全模型（沙箱 + 权限 + 审计） - OpenClaw 参考实现（五层解耦架构） 为什么火（技术文档维度）： - 真实案例支撑：OpenAI 团队实践，10x 开发速度数据 - 完整方法论：从原理到生产的完整路径 - 可执行架构：15+ 架构图 + 20+ 代码示例 - 踩坑经验：大量 "为什么" 和 "常见错误" 章节 - 参考实现：OpenClaw 开源项目可直接学习
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 延迟加载

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