深色模式
01 · 进阶自查
你的"Agent"可能只是个带工具的 prompt
📚 系列导航：这是《Agent 开发进阶》的第 1 篇（共 24 篇）。这门课要带你从"会调 API、跑过 demo"走到"能交付一个可评测、可运维的 Agent"，这一篇先给你一面镜子：照清自己现在到底站在哪一级。下一篇：02 · Workflow 还是 Agent。
⏱ 版本时效：本课涉及的 SDK/框架（Claude Agent SDK、OpenAI Agents SDK、LangGraph、MCP）API 演进快，示例基于 2026 上半年官方文档；以各家官方最新为准。
你大概率已经跑通过一个 agent demo：接了几个工具，演示时像模像样，群里发视频收获一片"牛"。但你心里可能也犯嘀咕——这东西敢不敢给真实用户用？我当年就是这个状态：demo 演示 10 次挑最好的 1 次给老板看，上线后真实成功率 40%，当场社死。demo 与产品的差距，不在功能在工程。这一篇只干一件事：用一套自查体系，帮你诚实地量出这个差距。
看完这一篇，你会拿到：
- 一个成熟度定级结果：你的项目落在 L1–L4 哪一级
- 一张 12 问自查表，每一问都指向本课的一篇解法
- 一份按短板排序的主攻篇目清单
- 一个从今天开始记录成功率的最小习惯
01 成熟度四级：从"能跑"到"无人值守"
先给标尺。L1 能跑 demo：理想输入下能出结果。L2 能处理边界：报错、重试、超时都有交代。L3 能被评测：有测试集、有成功率数字。L4 能无人值守：护栏、观测、熔断齐备，出了事能自己兜住或体面求助。
打个比方，这就像学车：L1 是在驾校场地里绕桩，L2 是应付得了突然窜出的电瓶车，L3 是有教练拿秒表打分，L4 才是独自上高速。多数项目卡在 L1 到 L2 之间——不是能力不够，是没人给过标尺。落地做法：现在凭直觉给自己预定一级，读完下一节再校对。
💡 一句话总结：L1 到 L4 不是功能多少的差距，是工程完备度的差距——先认标尺，再谈进阶。
02 自查 12 问：每一问都是一篇课
逐条回答，答不上来就算"否"：
| 问题 | 对应篇 |
|---|---|
| 1 成功率测过吗（有数字）？ | 19 评测 |
| 2 工具报错时循环会怎样？ | 04 循环 |
| 3 每个工具的调用正确率测过吗？ | 05 工具设计 |
| 4 system prompt 有分层结构吗？ | 06 上下文 |
| 5 输出能被程序稳定解析吗？ | 07 结构化输出 |
| 6 多步任务会先出计划吗？ | 08 规划 |
| 7 跨会话记得住用户偏好吗？ | 09 记忆 |
| 8 高危操作有人工审批吗？ | 12 人机协作 |
| 9 防过 prompt 注入攻击吗？ | 21 安全 |
| 10 跑一次任务多少钱？ | 22 成本 |
| 11 出问题能定位到哪一轮吗？ | 20 可观测 |
| 12 该不该拆多 agent 有判据吗？ | 15 多 Agent |
"否"超过 8 个是 L1，4–8 个大致 L2，少于 4 个且第 1 问为"是"才够 L3。这张表同时就是你的本课路线图。
💡 一句话总结：12 问就是 12 个工程缺口——你的"否"在哪，主攻方向就在哪。
03 诚实第一课：先量化成功率，再谈一切
进阶最难的不是技术，是心态。demo 文化的惯性是"挑最好的一次展示"，产品文化的起点是"统计最差情况的概率"。我那次 40% 成功率的社死之后学乖了：任何功能上线前，先拿 20 条真实输入连跑，记下成功几次——粗糙，但比"感觉挺稳"诚实一百倍。就像减肥先上秤，数字难看也得看。另一个虚荣陷阱是拿"接了 20 个工具"当能力指标——工具数量是虚荣指标，调用正确率才是真的。
💡 一句话总结：先有成功率数字，再有一切优化——没量过的系统，谈不上改进。
04 动手：给你的项目跑一遍 12 问
任务：拿你现有的 agent 项目（没有就用你最想做的那个构想），逐条回答 12 问，只许答"是/否/不知道"（"不知道"记为"否"）。数出"否"的个数定级，再把"否"对应的篇目按痛感排序，取前三作为主攻清单。
验收标准：一页纸，含三样东西——定级结果（L 几）、12 问逐条答案、主攻篇目前三名。
两种结果都正常：定级 L1 别沮丧，这门课就是为你设计的，按 04–07 顺序打地基；定级 L2 以上，恭喜，可以跳读，直接扑向主攻清单那三篇。
05 小结
你现在应该能：说出成熟度四级的判定标准、给自己的项目定级、拿出一份有排序的主攻篇目清单。
进阶 = 把"演示品"变"工业品"。但在写代码之前，还有个最贵的误区要先拆：很多人的问题不是 agent 写得不好，而是根本不该用 agent。下一篇 02 · Workflow 还是 Agent，先把架构观扶正。
📎 实战案例
开发者演示时挑 10 次里最好的一次给老板看，上线后真实成功率 40% 直接社死。他跑完 12 问自查，"否"占了 9 个、定级 L1 后才承认：问题不在功能，在没测过成功率。按主攻清单先补评测和工具设计，两个月后成功率提到 78%——进阶的第一课是诚实面对数字。
踩坑
- 我的第一个 agent 演示 10 次挑 1 次给老板看——上线首周被真实流量打回原形，成功率 40%。
- 把"接了 20 个工具"当能力指标，一个工具的调用正确率都没测过——数量是虚荣指标。
- 自查时给自己放水，把"大概能处理"答成"是"——三个月后照样返工，比当初诚实答"否"多花一倍时间。