ep20 · Agent 工程：从试验品到产品

• 模块：M4 Harness 核心
• 课节：11 节
• 配套音频：pm20-m4-播客.mp3（时长见集页）
• 配套字幕：pm20-m4-播客.srt
• 来源：xueai.miyang.cn（小山学堂 · 洛小山《学 AI 产品，从入门到精通》）

本集改编自小山学堂《学 AI 产品，从入门到精通》，音频为二次演绎配音版。音频讲主线与判断，文字稿给结构、清单和可复用的设计模板。

---

一、本集解决什么问题

很多人以为智能体的关键是模型够不够聪明，于是把精力全花在换更大的模型上。但真实情况恰恰相反：智能体工程 ≈ 80% 脚手架 + 20% 模型。大多数项目失败，败在错误处理不够健壮，模型够不够聪明反倒是次要的。

这一集讲的就是那 80%：循环怎么转、会在哪儿卡死、权限怎么分级、经验怎么封装成技能、工程护栏怎么装、多个智能体怎么协作、以及怎么让它不再是黑箱。

对产品经理而言，这一层几乎全是产品决策而不是技术决策：每个工具算不算危险操作、循环最多跑几轮、失败是自己重试还是停下来问人、用户能不能看见它在干什么花了多少钱——全部由产品拍板。

---

二、能力地图

层次	关键概念	它在回答什么	你该追问的问题
循环层	ReAct（思考 → 行动 → 观察）	它怎么把一件事做完	最多转几圈，每圈能动什么
故障层	5 种卡死模式	它会在哪儿失败	五种模式各自配了哪道防线
权限层	确认 / 自动 / 智能三种模式	它能做什么不能做什么	每个工具的风险等级谁定
经验层	Skill = 流程说明 + 工具指引	怎么让它少走弯路	哪些高频操作要预装技能
护栏层	5 道工程护栏	稳定性从哪来	迭代上限、截断、超时、恢复、急救
协作层	多 Agent 分工	复杂任务怎么拆	哪些能并行，哪些必须串行
观测层	事件流与用量追踪	它在干什么、花了多少	慢和贵的时候你有没有数据

读法两条。第一，越往下越决定「能用」还是「好用」：前三层决定能不能跑通，后四层决定能不能上线。第二，每一层都有硬编码的数字：最大迭代 50 轮、单次输出限制 200K 字符、上下文压缩阈值——这些数字是产品决策，不是技术默认值。

---

三、七个概念逐个拆开

1. ReAct 循环

Agent 的工作方式是「思考 → 行动 → 观察 → 再思考」的循环，一问一答只是其中一轮。

实例：用户要求「把项目里所有 console.log 删掉，然后跑测试确保没问题」。看似一句话，实际经历 14 轮循环，中间包含自我纠错。循环中有三部分在滚动：

• Thought（思考）：这一步的理由
• Action（行动）：实际调用的工具与参数
• Observation（观察）：工具返回的结果

同时有两个计数器值得盯：当前轮次（对应用户体验）与消耗 Token（对应成本）。

本质区别：聊天机器人给一段话就结束，执行结果它不知道；智能体自己执行、自己看结果、自己改主意。所以你要设计的不是一句提示词，而是这个循环的边界。

2. Agent 卡死的 5 种模式

故障模式	表现	对应防线
参数格式错误	该给数字的地方给了文字	参数校验
幻觉工具	调用了不存在的工具 / 函数	工具白名单验证
无限递归	两个步骤互相触发，空转	循环检测（重复动作即打断）
信息不足	没搞清需求但不问，硬做	主动提问机制
API 异常	外部服务超时 / 报错 / 脏数据	超时兜底，如实报告

关键提醒：这五种会互相叠加——信息不足时更容易编出不存在的工具，工具调用失败后又更容易陷入重试死循环。五道防线是并列关系，不是五选一。

3. 权限与安全

模式	做法	特点
确认模式（默认）	每个危险操作都需用户确认	最安全，最慢，打断流程
自动模式（危险）	所有操作自动放行	最快，最危险
智能模式	用 LLM 分类器评估风险等级，按级处理	折中，但判断本身可能出错

三个必须由 PM 拍板的设计决策：

1. 权限设计的核心矛盾是安全 vs 效率——每次弹窗都打断用户，不确认就可能造成不可逆破坏，你的产品选哪边？
2. 智能模式用 LLM 判断风险，而 LLM 判断也会错，一次误判可能删掉用户数据，这个风险能否接受？
3. 「只读」和「破坏性」是工具级别的标记。每个工具属于哪个风险等级，这是产品决策，不能推给工程。

示例：一次执行 5 个操作（读 2 个文件、改 1 个、删 1 个、执行 1 条命令）。确认模式下后三个弹窗；自动模式全部放行；智能模式下读取判为低风险放行，删除与执行命令判为高风险拦截。风险分级表必须提前写出来。

4. Skill 的本质：把经验写成操作手册

Skill = 流程说明 + 工具调用指引，目的是让 ReAct 循环尽可能短、尽可能高效。本质就是把经验写成文档，算不上新技术——用自然语言告诉模型：遇到这类任务先做什么、再做什么、调哪个工具。

「阳台收衣服」类比：没有 Skill 的智能体，像走到阳台才发现没拿衣架、回来拿、再发现要分开收、又回来；有 Skill 的，是出门前就把衣架、收纳袋和顺序想好，一趟搞定。差的不是手脚，是出门前那一份清单。

效率对比（发版任务）：

	轮次	Token	错误
无 Skill	12 轮	15,000	3 个
有 Skill	5 轮	4,000	0 个

效率差距 3.75 倍以上。

颗粒度最佳点：一个完整的工作流。太粗没有指导意义，太细不值得封装。写 Skill 的人是领域专家，用 Skill 的人是 Agent。

PM 必须回答的四个问题：为哪些高频操作预装 Skill？允许用户自建 Skill 吗？Skill 之间冲突了怎么办？谁来维护和更新？

5. 解剖一份真实的 Skill

一份完整的 SKILL.md 由四部分组成：

① 元信息（技能名称 / 描述 / 触发词）

触发词的覆盖度决定召回率。写得太少 → 该触发时没触发；写得太泛 → 不该触发时误触。好的触发词 = 穷举用户可能的自然表达。

② 适用条件（防误触的保险）

例：发版 Skill 判断两条——用户说了触发词？当前在项目目录？两条都 YES 才触发，否则静默退出，不干扰正常对话。没有这一层，用户在任何项目里说「发版」都会触发别人的发版流程，属灾难级 Bug。

③ 执行步骤（顺序 = 你认为正确的 SOP）

发版示例的 7 步管线：检查 Git → 运行测试 → 打包应用 → 更新版本 → 写发布日志 → 上传 COS → 同步落地页。

为什么先测试再打包？打包完才发现测试不过，那一轮的时间和 Token 就白花了。顺序不是技术细节，是你对正确做法的判断。

④ 允许工具（安全边界）

可用：run_command、edit_file、read_file、git、web_search

禁止：delete_file、启动子 Agent

——禁止删除防止误删；禁止子 Agent 是为了让执行链可预测。

⑤ 安全约束（最重要的部分）

• 不允许 force push（防止覆盖他人提交）
• 不允许跳过测试（无论多紧急）
• 失败时停止并报告，不自行重试（把控制权交还人类）

步骤写错了，Agent 只是做错事；约束缺失了，Agent 可能做危险的事。好的约束 = 明确的禁令 + 失败时的降级策略。

三个真实 Skill 的取舍示例：

Skill	流程	关键设计	安全约束
content-creator	风格画像 → 需求确认 → 大纲 → 研究 → 创作	先分析写作风格再动笔，不给模型直接生成的机会	允许联网搜索；禁止直接发布，需人工审核
web-importer	URL 识别 → 抓取 → 转换 → 写入笔记	自动识别三类网页走不同抓取逻辑	不保存需登录才能访问的页面
tag-organize	扫描 → 分析重复 → 合并建议 → 执行	合并前先给建议、等确认后再执行，绝不自动合并	不删除任何标签，只做合并

6. 脚手架、护栏、协作与可观测性

脚手架：Agent 工程 = 80% 脚手架 + 20% 模型。大多数项目失败败在错误处理不够健壮。包含工具注册、状态管理、错误恢复等「不起眼但决定生死」的部分。

5 道工程护栏（核心能力来自 LLM，稳定性来自护栏）：

护栏	防什么
迭代上限	防死循环（常见上限 50 轮）
输出截断	防撑爆（常见限制 200K 字符）
超时控制	防卡死
中断恢复	防损坏
上下文急救	防崩溃

没有护栏的 Agent = 没有刹车的跑车。

多 Agent 协作：主 Agent 拆任务 → 子 Agent 各司其职 → 汇总交付。调研员（只读）、开发者（可读写）、测试员（可读 + 运行）。运行在独立 Worker Thread，隔离内存，父级可随时中止子级。

原则：只读任务并行加速，写入任务串行保安全。

可观测性：事件流 + 统计面板，监控总耗时、LLM 调用次数、工具调用次数、输入 / 输出 Token、预估费用、文件变更。

每种事件类型都是产品决策点：text 用于流式展示、tool_start/end 用于进度条、usage 用于计费、error 用于告警。可用 OpenTelemetry 标准记录 spans，再用任意 APM 工具分析。

全景图：LLM 提供智能，工具提供能力，记忆提供连续性，循环提供自主性，工程提供稳定性——五个缺一不可，前四个的成败最终落在第五个上。

---

四、审查清单

上线任何一个 Agent 功能前，按顺序过这九条：

1. 循环边界：最多转几圈？每圈允许动哪些工具？什么时候必须停下来问人？
2. 五道防线：参数校验、工具白名单、循环检测、主动提问、超时兜底，是否五道都有（不是五选一）？
3. 风险分级表：每个工具属于只读 / 可写 / 破坏性哪一级？这张表是否提前写出来了？
4. 权限模式：确认 / 自动 / 智能选了哪种？误判风险是否可接受？
5. Skill 覆盖：高频操作是否预装了 Skill？触发词是否穷举？适用条件能否防误触？
6. 约束条款：每个 Skill 有没有写死红线？失败时是停止报告还是自行重试？
7. 护栏数字：迭代上限、输出截断、超时阈值分别是多少，依据是什么？
8. 协作策略：哪些子任务并行、哪些串行？父级能否中止子级？
9. 可观测性：能否看到耗时、调用次数、Token 与预估费用？错误事件是否接了告警？

---

五、约束说明

以下约束来自本集原始素材，属于设计与承诺时的边界条件：

1. 模型不是瓶颈。80% 是脚手架，20% 是模型。把预算全花在换更大模型上是错配。
2. 智能模式的判断本身会出错。用 LLM 评估风险等级，一次误判可能删掉用户数据，必须有不可逆操作的兜底。
3. 只读与破坏性是工具级标记。这个分级是产品决策，不能推给工程。
4. Skill 的适用条件不是可选项。缺少适用条件会导致跨项目误触发，属灾难级 Bug。
5. 约束比步骤更重要。步骤写错只是做错事，约束缺失可能做危险的事。
6. 写入任务不可并行。多个角色同时改同一文件的后果不可恢复。
7. 护栏数字是产品决策。50 轮迭代上限、200K 字符输出限制这类数值需要有人负责，不能沿用默认值。
8. 没有可观测性即黑箱。无法回答「为什么慢」「为什么贵」的产品，无法优化成本和体验。
9. 本集不含题库内容。本集无题库页，全部素材均为正文讲解。

---

六、实践提示

提示一 · 上线前先写一张「工具风险分级表」

把你的 Agent 能调用的每一个工具列出来，逐个标注只读、可写、破坏性三级，并写明每一级在哪种权限模式下如何处理。这张表是整个权限设计的核心交付物，也是后面所有讨论的依据。做这张表的过程本身就会暴露问题——你经常会发现某个工具既会读又会删，那就说明它该拆成两个。分级表写完，权限模式的选型自然就清晰了，不需要反复争论。

提示二 · 用「循环轮次」而不是「任务完成率」做早期验收

早期评估 Agent 效果时，别只看最终有没有做对，要看它跑了几轮。同一个任务从十四轮降到六轮，意味着成本减半、延迟减半、出错机会也大幅下降。把轮次数和 Token 数做成每次迭代的固定观测项，你会很快发现哪些环节在空转。大多数时候，降低轮次最有效的手段不是换模型，而是补一份 Skill 或者把工具参数说明写清楚。

提示三 · 给每个 Skill 写「反面用例」

写 Skill 的时候，除了触发词和步骤，额外加一节反面用例：列出哪些表达不应该触发这个技能，以及哪些情况下触发了也要立刻退出。这一节能挡掉绝大多数误触发的工单。真实经验是，触发词写得太泛带来的问题，远比写得太少带来的问题严重——漏触发用户会换种说法再说一遍，误触发则可能直接做错事。

提示四 · 把护栏数字写进产品文档并指定负责人

迭代上限、输出截断、超时阈值这三个数字，必须写进产品文档，并且明确谁有权调整。常见的问题是这些值沿用了框架默认值，没人验证过是否适合当前场景，等到线上出现死循环或者单次调用费用异常时，才发现阈值定得离谱。指定负责人之后，这些数字会随真实用量数据被定期复核，而不是永远停留在最初拍脑袋的那个值。

---

七、可带走的判断清单

1. 把精力从选模型移到画边界。智能体工程约 80% 是脚手架、20% 是模型，你要设计的是循环圈数、每圈能动什么、何时必须停下来问人。
2. 为五种卡死模式逐条写下应对方案，且五道防线是并列关系而非五选一。这五类不是理论，是上线后一定会来的工单。
3. 权限分级必须产品拍板。只读与破坏性是工具级标记，风险分级表要提前写出来，不能推给工程。
4. 把高频操作写成 Skill。盯紧四件事：触发词够不够全、适用条件能否防误触、步骤顺序是不是你认可的正确流程、约束有没有写死红线。
5. 上线前先装护栏和仪表盘。五道护栏是迭代上限、输出截断、超时控制、中断恢复、上下文急救；可观测性至少要看到耗时、调用次数、Token 和预估费用。

这五条的共同点：智能体的能力来自模型，但可靠性来自你写的工程。模型负责聪明，你负责让它可控。

---

八、音频与文字稿说明

• 音频为单人口播，面向非工程背景听众，全程不直接口播英文缩写，数字以中文读法呈现。
• 文字稿按「能力地图—概念拆解—审查清单—约束说明—实践提示」组织，可直接作为团队内部培训材料使用。
• 音频的八段结构与本文第三、四节对应，建议先听音频建立主线，再回到本文查清单。

---

来源：xueai.miyang.cn（小山学堂 · 洛小山《学 AI 产品，从入门到精通》）