AI 智能体设计模式与最佳实践
核心原则
第一性原理
从李世石与 AlphaGo 的围棋对战中的第 37 手，我们可以总结出第一性原理智能体的基本原则：
- 仿生智能体 (Replica agents)：当流程需要人工审核、代理作为用户的副驾驶员或与仅限 UI 的旧版工具集成时，使用仿生学
- 外星智能体 (Alien agents)：当目标是纯粹的结果效率时，使用第一性原理
验证不对称性定律
验证与验证者的不对称性定律：
所有可解决且易于验证的问题，都将被 AI 解决。
智能体流量
高度完善的 UI 和企业应用的价值将下降， 高性能、可靠、可扩展的 API 的价值将上升。
设计模式
智能体设计模式：
- 给智能体一台计算机（CLI 和文件）
- 渐进式披露
- 卸载上下文
- 缓存上下文
- 隔离上下文
- 演化上下文
智能体原生架构
智能体原生应用应该：
- 对等性 (Parity)：用户通过 UI 完成任务
<->智能体通过工具实现 - 细粒度 (Granularity)：工具应该是原子原语
- 可组合性：有了以上两点，只需编写新的提示词即可创建新功能
- 涌现能力
- 文件作为通用接口：文件用于可读性，数据库用于结构
- 随时间改进：
- 累积上下文：状态在会话之间持续存在
- 开发者级优化：系统提示词
- 用户级定制：用户提示词
智能体原生产品
构建强大的基础， 观察用户要求智能体做什么， 将涌现的模式形式化：
- 常见模式：领域工具
- 频繁请求：专用提示词
- 未使用的工具：删除
递归语言模型
RLM 通过分治与递归，实现多跳推理代码，解决长文本带来的 上下文腐烂 问题。
指令编写
- 使用现有文档：使用现有的操作程序、支持脚本或政策文档来创建 LLM 友好的例行程序
- 提示智能体分解任务：提供更小、更清晰的步骤有助于最大限度地减少歧义，并帮助模型更好地遵循指令
- 定义清晰的行动：确保例行程序中的每一步都对应一个特定的行动或输出
- 捕获边缘情况：实际交互通常会产生决策点，一个健壮的例行程序会预测常见的变化，并包含关于如何通过条件步骤或分支来处理它们的指令，例如在缺少所需信息时提供替代步骤
如何编写优秀的 AGENTS.md 来自超过 2500 个仓库的经验教训：
- 明确角色：定义智能体是谁（专家技术作家），拥有什么技能（Markdown、TypeScript），以及做什么（阅读代码、编写文档）
- 可执行命令：给 AI 可以运行的工具（
npm run docs:build和npx markdownlint docs/）。命令排在第一位 - 项目知识：指定带有版本的技术栈（React 18、TypeScript、Vite、Tailwind CSS）和确切的文件位置
- 真实示例：使用实际代码展示好的输出是什么样的。没有抽象描述
- 三层边界：使用始终做、先问、从不做来设置清晰的规则。防止破坏性错误
提示
角色 → 工具 → 上下文 → 示例 → 边界
Vibe Coding
- 规范工作：
- 目标：选择下一个最高杠杆目标
- 分解：将工作分解为小的、可验证的切片（拉取请求）
- 标准：编写验收标准，例如输入、输出、边缘情况、UX 约束
- 风险：提前指出风险，例如性能热点、安全边界、迁移问题
- 给智能体上下文：
- 仓库：仓库约定
- 组件：组件系统、设计令牌和模式
- 约束：定义约束：什么不能碰，什么必须保持向后兼容
- 指导智能体"做什么"，而不是"怎么做"：
- 工具：分配正确的工具
- 文件：指向相关文件和组件
- 约束：说明明确的防护栏，例如
不要更改 API 形状、保持此行为、没有新依赖
- 验证和代码审查：
- 正确性：边缘情况、竞争条件、错误处理
- 性能：
N+1查询、不必要的重新渲染、过度获取 - 安全性：认证边界、注入、机密、SSRF
- 测试：更改行为的覆盖率
- 集成和发布：
- 将大工作分解为智能体可以可靠完成的任务
- 合并冲突
- 验证 CI
- 分阶段推出
- 监控回归
提示
规范 → 上手 → 指导 → 验证 → 集成
系统
OpenAI Codex 系统提示词：
- 指令
- Git 指令
AGENTS.md规范- 引用指令
编码
AGENTS.md应该定义项目的 为什么、是什么和怎么做- 少即是多：在文件中包含尽可能少的合理指令
- 保持
AGENTS.md的内容简洁且普遍适用 - 使用渐进式披露：不要告诉智能体所有要知道的信息，告诉智能体什么时候需要，如何找到和使用它
- 智能体不是 linter：使用 linter 和代码格式化程序，以及其他功能如 Hooks 和 Slash Commands
AGENTS.md是控制的最高杠杆点，所以避免自动生成它。你应该仔细制作其内容以获得最佳结果
拉取请求
GitHub Copilot 更快地调试问题：
测试
研究
由复杂的 LLM 提示驱动的 AI 智能体：
- 深度研究智能体来自 Claude 智能体烹饪书
- DeepCode：开放式智能体编码
- 生成式智能体
- Minecraft 智能体
工具
工具执行：
- 工具调用：原子工具包
- Bash：可组合的静态脚本
- 代码生成：动态程序
上下文
动态发现
动态上下文发现：
- 工具响应 → 文件
- 终端会话 → 文件
- 上下文压缩时引用对话历史
- 按需加载
- 渐进式披露
个性化
用于记忆提取的元提示：
记忆系统
记忆系统：
- 可重复的记忆循环：注入 → 推理 → 蒸馏 → 巩固
- 强制优先级：当前用户消息 > 会话上下文 > 记忆
上下文工程
LLM 并未统一利用其上下文，它们的准确性和可靠性随着输入令牌数量的增加而下降，称为上下文腐烂。
因此，仅仅在模型的上下文中拥有相关信息是不够的：信息的呈现方式对性能有显著影响。这凸显了上下文工程的必要性，优化相关信息的数量并最小化不相关上下文以实现可靠的性能，例如自定义 Gemini CLI 命令。
使用文件进行规划
工作流
计划模式
Claude code EnterPlanMode 系统提示词：
调试模式
Cursor 调试模式：
- 假设：生成多个假设
- 日志：添加日志点
- 收集：收集运行时数据（日志、跟踪、分析）
- 定位：复现 bug，分析实际行为，精确定位根本原因
- 修复：基于证据，进行有针对性的修复
测试驱动开发
- 编写测试：让智能体根据预期的输入/输出对编写测试。明确说明在做 TDD，避免智能体为尚不存在的功能编写模拟实现
- 运行测试：让智能体运行测试并确认测试确实失败。明确说明在这个阶段不要编写实现代码
- 提交测试
- 编写代码：让智能体编写能通过测试的代码，并指示它不要修改测试。告诉它持续迭代，直到所有测试通过
- 提交代码
编排
单智能体系统
多智能体系统：管理者模式
其余智能体作为工具，由中心智能体调用：
多智能体系统：去中心化模式
多个智能体作为对等体运行：
防护栏
构建防护措施
- 相关性分类器：确保智能体响应保持在预期范围内，通过标记偏离主题的查询
- 安全分类器：检测试图利用系统漏洞的不安全输入（越狱或提示注入）
- PII 过滤器：通过审查模型输出中任何潜在的个人身份信息 (PII)，防止不必要的个人身份信息泄露
- 内容审核：标记有害或不当的输入（仇恨言论、骚扰、暴力），以保持安全、尊重的互动
- 工具安全措施：通过评估您智能体可用的每个工具的风险，并根据只读与写入访问、可逆性、所需的账户权限和财务影响等因素分配低、中或高评级。使用这些风险评级来触发自动化操作，例如在高风险功能执行前暂停进行防护栏检查，或在需要时升级到人工干预
- 基于规则的保护：简单的确定性措施（黑名单、输入长度限制、正则表达式过滤器）以防止已知的威胁，如禁止的术语或 SQL 注入
- 输出验证：通过提示工程和内容检查确保响应与品牌价值一致，防止可能损害品牌完整性的输出
当超出失败阈值或高风险操作时，触发人工干预计划，是一项关键的安全保障措施。
评估
智能体评估：
- 尽早开始
- 从失败中获取现实任务
- 定义明确、稳健的成功标准
- 仔细设计评分器并结合多种类型（基于代码、基于模型、人工）
- 确保问题对模型来说足够困难
- 迭代评估以提高信噪比
- 阅读记录
- 选择框架：prompt foo、harbor
构建智能体时，跟踪是事实来源：
- 调试变为跟踪分析
- 测试变为评估驱动
- 无法在推理中设置断点
- 性能优化变化：任务成功率、推理质量、工具使用效率
基准测试
基准测试：
- 综合：不要过分关注一个基准测试上 1-2% 的领先优势，专注于特定和全面的领域
- 相对：在同一模型系列或实验室内进行比较，从 v1 到 v2 的分数如何变化？
- 验证：最终唯一重要的基准测试是您的工作负载
库
指令
RAG
- RAGFlow：AI 智能体的卓越上下文层
项目
- VibeKanban：无冲突地并行运行编码智能体，并执行代码审查
文档
演示文稿
- Banana：基于 nano banana pro 的 AI 原生 PPT 生成器