一、先把结论说透：自建 AI Agent，难点不在"接模型"，而在"管住系统"
很多人理解 AI Agent，容易停留在"让模型自己干活"这一步。可真正进入生产环境后，你会发现，模型只是大脑，真正决定系统能不能稳定运行的，是大脑外面那一整套"驾驭装置"。
一个能用的 Agent，需要知道任务目标；一个好用的 Agent，需要知道什么时候查资料、什么时候调用工具、什么时候停止；一个能进生产的 Agent，还要知道预算、权限、失败、日志、成本、输出结构和恢复策略。
这份资料最有价值的地方，是把前面大量分散的工程模式收束成一个可迁移的实战案例：用代码审查场景，把 16 个核心模式串成一条完整链路。它告诉我们：不要试图复刻某个成熟产品的所有细节，而要迁移它背后的工程思想。
换句话说，真正应该学的不是某个按钮、某个工具名、某个内部实现，而是"如何把 Agent 做成一个可控系统"。
二、为什么不是复刻产品，而是迁移模式
成熟的 AI 编码工具往往包含很多产品特定能力：终端界面、几十个内置工具、会话格式、订阅体系、权限交互、插件生态。这些细节很强，但并不一定适合你的业务。
你的 Agent 可能不是编码助手，它可能是安全扫描器、数据监控员、客服质检员、投研分析员、运维诊断员、合同审阅员。不同场景的外壳不同，但内核问题高度相似：输入从哪里来？上下文怎么装？工具怎么用？危险动作谁审批？失败后如何重试？结果如何被机器继续消费？
所以，自建 Agent 的正确路线不是"照着产品抄一遍"，而是把通用模式抽出来，再落到自己的场景里。
|----------|-----------------|---------------------|
| 错误思路 | 正确思路 | 原因 |
| 复刻全部功能 | 迁移核心模式 | 功能会随产品变化，模式才能跨场景复用 |
| 只关注模型效果 | 关注工程控制面 | 模型会出错，工程层负责限制、恢复和记录 |
| 让模型直接执行 | 让模型提出请求，代码验证后执行 | 安全边界必须掌握在系统手里 |
| 输出一段自然语言 | 输出结构化报告 | 结构化结果才能进入后续自动化流程 |
三、项目定义：用代码审查 Agent 验证工程模式
资料选择了一个非常适合练手的场景：输入一份 Git diff，输出一份结构化代码审查报告。这个场景很典型，因为它天然覆盖了 Agent 构建的六个关键维度。
第一，它需要读取变更内容，所以一定会遇到上下文预算问题。第二，它需要搜索关联文件，所以一定会涉及工具编排。第三，它要判断 bug、安全风险和设计问题，所以需要稳定的提示词控制。第四，它只能审查，不能乱改，所以要有权限边界。第五，模型调用和工具调用都可能失败，所以要有重试和熔断。第六，审查结果要可追踪，所以要有日志、指标和报告结构。
这个 Agent 的输入、输出和约束可以概括为三句话：输入是一份 diff；输出是带文件、行号、严重级别、分类、修复建议的审查报告；执行过程只读、有预算、可追踪。
四、整体架构：一个 Agent 至少要有六层能力
一个常见误区是：Agent Loop 就是"模型回答一次，再根据结果调用工具"。这个理解太浅。真正的 Agent Loop 更像一个状态机：每一步都要经过预算、权限、工具、重试、日志的共同约束。
资料中的实现把代码审查 Agent 拆成六层：提示词架构、上下文管理、工具与搜索、安全与权限、韧性、可观测性。每一层都不是装饰，而是生产级系统必须有的能力。
|----------|--------------------|---------------|
| 层级 | 核心职责 | 对应问题 |
| L1 提示词架构 | 定义规则、角色、输出格式、行为边界 | 模型到底应该怎么想、怎么答 |
| L2 上下文管理 | 控制输入规模、截断策略、预算记账 | 有限窗口里装哪些信息 |
| L3 工具与搜索 | 让模型提出工具请求，由系统验证执行 | 如何查更多信息而不失控 |
| L4 安全与权限 | 失败关闭、白名单、调用上限、只读约束 | 模型会不会越权干危险事 |
| L5 韧性 | 重试、熔断、降级、避免循环浪费 | 失败后怎么继续或停止 |
| L6 可观测性 | 事件、指标、覆盖率、成本、报告 | 系统到底做了什么、效果如何 |
五、第一层：提示词架构 - 把提示词当成控制面，而不是文案
很多人写提示词，像写一段说明书：越长越好，越细越安心。但工程化的提示词不是一坨文本，而是分层控制面。
资料里的关键思想是：把稳定的规则和动态的信息分开。稳定的部分可以理解为"宪法层"：审查原则、严重级别定义、输出字段、行为约束。动态的部分可以理解为"运行时层"：当前 PR 标题、变更文件、语言特定规则、当前任务背景。
这种拆法有三个好处。第一，稳定规则更容易维护，不会因为每次任务变化而被污染。第二，未来接入缓存时，稳定部分更容易复用。第三，模型更容易区分"长期规则"和"当前任务信息"，减少指令混乱。
5.1 静态宪法层：让模型知道什么永远不变
宪法层解决的是"原则"问题。比如：优先发现正确性问题，其次关注安全风险，再关注性能和可维护性；输出必须包含文件、行号、严重级别、分类和建议；不要因为风格偏好制造噪音；不确定时降低严重级别。
这些内容一旦确定，就不应该在每次任务里随意变化。它们是 Agent 的长期行为边界。
5.2 动态运行时层：让模型知道当前要处理什么
运行时层解决的是"现场"问题。比如：本次 diff 涉及哪些文件，主要语言是什么，PR 标题是什么，当前是否是安全相关变更，是否需要关注接口兼容性。
动态信息应该靠后放，避免污染稳定前缀。这样做不仅清晰，也更符合缓存友好的设计思路。
5.3 结构化输出：不要让模型自由发挥
代码审查报告如果只是自然语言，后续就很难自动处理。结构化输出的价值在于：每条发现都能被机器读取、筛选、排序、计数、归档。
这也是"提示词即控制面"的关键：提示词不只是告诉模型"你是谁"，还要告诉它"输出必须是什么形状"。
六、第二层：上下文管理 - Token 预算就是 Agent 的内存管理
Agent 的上下文窗口不是无限仓库，而是一块昂贵、有限、容易被污染的工作内存。把所有内容都塞进去，看似信息完整，实际上会导致成本升高、延迟变长、注意力分散，甚至让重要信息被挤掉。
资料里的实现采用双层预算：总预算控制整次审查规模，单文件预算防止某个大文件吞掉全部空间。更重要的是，内容被截断时，不是静默丢弃，而是明确告诉模型：这里只展示了一部分，完整内容有多少。
6.1 为什么要显式告知截断
静默截断是上下文管理里最危险的坏习惯。模型不知道自己没看全，就可能基于局部内容做出过度自信的判断。
显式告知截断，本质是在保护模型的认知边界：你看到的是局部内容，不能假装自己看到了全部。
6.2 保守估算比精确估算更适合工程落地
Token 精确计算依赖具体分词器和模型版本。对于 Agent 系统来说，保守估算通常更实用：宁可少塞一点，也不要临界溢出。
工程系统追求的不是每次都把窗口塞满，而是稳定、可预测、可恢复。
七、第三层：工具与搜索 - 模型提出需求，系统负责执行
工具能力是 Agent 和普通聊天机器人的重要分界线。但工具越强，风险越大。资料中的设计非常关键：模型不能直接执行工具，它只能输出工具请求；真正执行之前，系统会检查工具类型、输入内容、权限范围和调用次数。
这就像公司里的审批流：员工可以提交需求，但不能绕过流程直接动生产系统。
7.1 bash 是强大的通用接口，但必须关进笼子
对模型来说，命令行是一种天然熟悉的工具接口。查文件、搜关键字、统计行数、看目录结构，都可以通过只读命令完成。
但命令行同时也很危险。真正安全的做法不是完全禁用，而是只允许读操作，阻止写操作、联网、删除、脚本执行、输出重定向和危险元字符。
7.2 Skill 是专项分析能力包
除了通用搜索，还可以为 Agent 准备专项分析能力，比如安全审计、性能审查、接口兼容性检查、语言习惯检查。
Skill 的价值在于复用专家经验：每次遇到类似问题，不必让模型从零思考，而是调用一套经过整理的专项判断框架。
八、第四层：安全与权限 - 渐进式自主，不是无限放权
很多人希望 Agent 越自主越好，但生产环境里，自主必须和安全绑定。越能干的 Agent，越需要清晰边界。
资料里的代码审查 Agent 是只读场景，所以安全策略非常明确：LLM 后端只处理文本；工具只允许白名单命令；危险命令显式禁止；输出重定向拦截；每个文件工具调用次数有限；工具执行有超时；输出结果有限长。
8.1 失败关闭：不确定就拒绝
安全系统最怕"猜测式放行"。失败关闭的原则是：如果无法判断是否安全，就默认拒绝。
这个原则会牺牲一点便利性，但能换来可控性。对 Agent 来说，可控性比"显得很聪明"更重要。
8.2 渐进式自主：从只看，到只读工具，再到生态调用
好的权限设计不是只有"允许"和"禁止"两个档位，而是逐步放权。第一阶段只让模型看 diff；第二阶段允许它请求只读工具；第三阶段才允许通过 MCP 变成其他 Agent 可以调用的能力。
这种分级设计能让系统随着信任度增加而扩展，而不是一开始就把所有权限打开。
九、第五层：韧性 - 没有上限的重试不是可靠，而是浪费
生产系统一定会失败。模型接口会限流，网络会波动，工具会超时，输出会格式错误。真正的韧性不是"永远不失败"，而是"失败后知道怎么处理"。
资料里的韧性设计包含三件事：有限重试、熔断器、局部能力降维。有限重试避免无限循环；熔断器避免连续失败继续烧钱；局部能力降维让系统在信息不完整时仍能给出有边界的结果。
9.1 有限重试：给失败一个窗口，也给成本一个上限
一次失败可能只是偶发问题，所以可以重试。但重试必须有上限，而且最好逐步拉开间隔。
没有上限的重试会把系统拖入死循环，尤其在 Agent 场景里，模型调用成本和工具调用成本都会被快速放大。
9.2 熔断器：连续失败就停下来
当连续多个文件都审查失败时，继续硬跑通常没有意义。熔断器的作用就是在系统进入异常模式时及时止损。
这不是放弃任务，而是保护系统：先停下来，记录失败原因，再让人或外层调度器决定下一步。
9.3 局部能力降维：做不到满分，也要做可解释的 60 分
当文件太大无法完整审查时，可以只审查截断部分，但必须写明限制。工具不可用时，可以退回纯 diff 审查。
这叫能力降维：不是假装一切正常，而是在能力范围内交付可解释结果。
十、第六层：可观测性 - 先观察再修复
很多 Agent 项目失败，不是因为模型差，而是因为系统出了问题没人知道。它到底审查了几个文件？跳过了哪些？工具调用失败几次？每个发现大概花了多少成本？哪里最慢？
如果这些问题答不上来，就谈不上优化。
10.1 事件日志：记录关键节点，而不是记录所有废话
可观测性不是把所有内容都打印出来。尤其在代码审查场景，日志里不应泄露代码细节、文件敏感路径或密钥信息。
更合理的方式是记录结构化事件：审查开始、文件审查完成、工具调用结果、审查结束、发现数量、预算使用、耗时和成本。
10.2 ReviewReport：让结果本身也成为指标
最终报告不只是给人看的文本，也应该包含机器可读的指标：审查文件数、跳过文件数、总 Token 使用、耗时、发现数量、严重级别分布。
这些指标会让你知道 Agent 是否真的有价值，而不是凭感觉判断。
十一、实战验证：让 Agent 审查自己的代码
一个系统是否可靠，不能只看设计图，必须拿真实任务验证。资料中最有代表性的做法，是让代码审查 Agent 去审查自己的实现。
这种自举测试非常有价值。因为 Agent 不仅要理解业务逻辑，还要识别自身工具层、安全层、解析层、预算层里的问题。
11.1 它能发现哪些类型的问题
在示例中，Agent 能发现多类问题：diff 解析边界情况、原子计数器溢出风险、JSON 解析脆弱性、大文件重复遍历带来的性能浪费。
更重要的是，它还能发现工具系统里的安全问题：如果命令通过 shell 解释器执行，即使开头命令在白名单里，也可能被元字符绕过。
11.2 自举测试的真正意义
自举不是炫技，而是验证闭环。Agent 发现问题，人类修复问题，Agent 再次验证修复。这就是一个可持续改进系统的雏形。
任何安全层都不是一次设计就万无一失，持续审查和复验才是长期防线。
十二、闭环升级：让其他 Agent 调用你的 Agent
一个 Agent 如果只能独立运行，价值是有限的。如果它能以标准协议暴露成工具，就能进入更大的 Agent 生态。
资料里的代码审查 Agent 可以切换成 MCP Server 模式，把"审查 diff"暴露成外部工具。这样，另一个编码 Agent 可以在修复前先调用它审查，拿到结构化 findings，再逐项处理。
这一步非常关键。它意味着你构建的不是一次性脚本，而是可被组合、可被调用、可被纳入工作流的能力模块。
未来的 Agent 系统很可能不是一个超级助手解决一切，而是一组专职 Agent 通过标准协议协作：审查、测试、修复、发布、监控、回滚，各司其职。
十三、模式组合：真正困难的是处理模式之间的张力
单独理解某个模式并不难，难的是组合使用。比如"为一切设定预算"和"编辑前先读取"之间就有张力：完整读取更安全，但完整读取可能超过预算。
又比如"缓存感知设计"和"动态上下文注入"也有张力：动态内容太靠前，会破坏稳定前缀；动态内容太靠后，又可能影响模型理解。
所以，自建 Agent 的关键不是把模式清单全部塞进去，而是知道每个模式解决什么问题、会引入什么副作用，以及和其他模式如何配合。
十四、普通团队如何落地：六步走，不要一步登天
很多团队一上来就想做"全自动工程师"，结果很快被权限、上下文、成本、工具、安全问题打垮。更稳妥的路线，是从一个小而清晰的 Agent 开始。
14.1 第一步：先做只读 Agent
只读 Agent 的风险最低，最适合起步。比如代码审查、日志分析、文档问答、告警归因，都可以先从只读开始。
14.2 第二步：加入上下文预算
一旦输入变多，就必须加预算。没有预算的 Agent，很快会变成成本黑洞。
14.3 第三步：加入工具，但只允许安全工具
工具能显著提升能力，但一开始最好只开放查询、搜索、统计类能力。写操作、联网、删除、执行脚本都应谨慎。
14.4 第四步：加入安全闸门
白名单、黑名单、超时、输出截断、调用次数上限，这些看起来基础，却是生产环境里最重要的护栏。
14.5 第五步：加入韧性和观测
当任务开始规模化运行，失败会成为常态。重试、熔断、降级和日志指标必须跟上。
14.6 第六步：通过协议接入生态
当能力稳定后，再把它暴露成 MCP 工具，让其他 Agent 或工作流调用。这样你的 Agent 才能从单点工具变成生态节点。
十五、完整架构回顾：AI Agent 是一套工程系统
把整套思路收束起来，可以得到一个很清晰的判断：AI Agent 的核心不是"更会说"，而是"更可控"。
它需要提示词定义行为，需要上下文管理资源，需要工具连接外部世界，需要安全层限制越权，需要韧性层处理失败，需要可观测层让团队知道它做了什么。
如果少了提示词层，模型容易乱答；少了上下文层，成本和信息污染会失控；少了工具层，Agent 只能空谈；少了安全层，风险不可接受；少了韧性层，系统经不起异常；少了可观测层，团队无法持续优化。
十六、给技术团队的落地清单
|---------|------------------|----------------|
| 检查项 | 应该做到什么 | 为什么重要 |
| 提示词分层 | 稳定规则与动态信息分开 | 减少混乱，为缓存和维护打基础 |
| 输入预算 | 总预算、单文件预算、工具输出预算 | 防止上下文爆炸和成本失控 |
| 截断说明 | 截断必须显式告知模型 | 避免模型基于局部信息过度自信 |
| 工具请求协议 | 模型提请求，系统验证执行 | 把执行权留在工程层 |
| 只读优先 | 先从查询、搜索、统计类工具开始 | 降低起步风险 |
| 权限多层防护 | 白名单、黑名单、超时、调用上限 | 任何单层失效仍有备用防线 |
| 重试有限 | 接口失败可重试，但必须有上限 | 避免成本黑洞和死循环 |
| 熔断机制 | 连续失败后暂停任务 | 保护系统稳定性 |
| 结构化结果 | 输出可被机器读取的报告 | 方便后续修复、复验和统计 |
| 可观测指标 | 记录覆盖率、耗时、成本、失败原因 | 优化必须建立在数据上 |
十七、总结：未来不是"会聊天的模型"，而是"可治理的 Agent 工程"
这份资料真正重要的启发是：AI Agent 的竞争力，不只是模型能力，而是模型外面的工程控制面。
当模型越来越强，团队之间的差距会逐渐转向：谁更会管理上下文，谁更会设计工具边界，谁更会做权限治理，谁更会处理失败，谁更会观测成本与质量，谁更会把多个 Agent 组合成稳定工作流。
自建 Agent 的第一性原则不是"让模型尽可能自由"，而是"让模型在正确边界内高效行动"。
一句话总结：真正的 AI Agent 工程，不是把模型接进系统，而是给模型装上方向盘、刹车、仪表盘、安全带和导航系统。
参考资料：https://pan.baidu.com/s/1Fm6rZSZkY3q2NcrmTfTMeQ?pwd=6fkr