先看一个真实到有点刺眼的场景。
需求只有一句话：接入公司支付接口，新增退款功能，保证重试不会重复退款。编程智能体十分钟就给出了补丁，编译通过，单元测试也通过。评审时平台工程师却发现，它导入的是去年已经停用的版本，认证方式抄自公开示例，而那组”恰好通过”的单元测试，把同一个错误又复制了一遍。
这不是一句”模型偶尔会幻觉”能解释的事。
微软这份手册到底写了什么
十月九日，微软开发者关系团队发布了《智能体体验实践手册》（Agent Experience Practitioner Playbook）。主笔是微软首席开发者布道师 Waldek Mastykarz，发布在微软官方开发者博客上，正文之外还提供一份免费手册下载，以及一个可以装进编程智能体里随时提问的技能包。
它不是又一篇”如何写好提示词”，而是一套方法论：怎么测出编程智能体在你的技术栈上会犯什么错，怎么查出错的根因，以及怎么在源头把它修掉。
数据来源也不轻：从二〇二五年秋天开始，这个团队就用真实开发者会写的那类需求，在 Azure、Cosmos DB、SharePoint Framework、Microsoft 365 Copilot 扩展这几套自家技术上持续测量智能体表现，把结论按月写成系列文章。这份手册是把散落的文章拼成一条完整链路。他们称，这些评测带来了几十项已上线的文档与工具修复，其中一套开发工具包就有四十六项改进。
核心主张：等模型变强，不是策略
手册里最值得记住的一句判断是：等待模型变好并不是一种策略。 因为一个知识截止日期，说明不了这个模型对你的产品究竟了解多少。
它给的替代思路是：一个技术或平台能改的，其实是智能体日常依赖的那几个面——文档、MCP 工具、技能包、插件、指令文件、命令行工具和接口。这些是平台方自己就能动的。
这个判断对国内做工具的人尤其有参考价值。很多团队把智能体答不上来归因于”模型不行”，然后等着下一代模型上线。但如果是自家文档里没有正确示例、接口的描述文件过时、技能包没被检索到，换哪个模型都一样。
评测会骗人，而且骗得很像真的
手册里最实用的一节，是承认评测本身经常不可信。官方举了两个例子：
- 有代码从来没有编译通过，评测却给了满分；
- 有一项”是否使用了某平台”的检查，无论用没用都会通过。
微软自己的总结是：一项在所有输入上都通过的检查，什么也没测出来。所以他们要求评测结果必须同时具备两样东西——判据（criteria）和闸门（gate）。判据负责判断语义，闸门负责证明这份代码真的跑起来了。而写判据是整件事里最难的一步：判据必须让评审者在不同时间点得到一致的结论，被信任之前要先校准，产品改动之后要跟着改版本。手册还专门提醒：别让模型替你写判据。
另一个被反复强调的区分是”读数”和”轨迹”。读数告诉你哪一项失败了，轨迹才告诉你为什么。同一种失败在读数上看起来一模一样，但根因可能完全不同：扩展根本没被加载、加载了却从没被调用、调用了但用法错了——这三种要修的地方分别在发现机制、触发机制和内容质量上，改错一个就是白干。
九类失败模式，以及一套可落地的归因
微软说，在它评测过的所有技术栈上，反复出现的失败模式收敛到了九类，每一类都指向”应该先去检查哪个面”。官方博客没有把九条逐条摊开，被点名最多的表现是：选了错误的版本、用了已经过时的认证方式、给出任何一个产品团队都不会推荐的配置方式。
把这套方法搬到自己的项目上，落笔前可以先按四类缺口归因，这也是我在读完后觉得最省事的一刀：
- 知识缺口：智能体压根不知道这个内部接口存在，或者只见过旧版本。修法是补权威范例和迁移说明，不是换模型。
- 工具缺口：它有检索能力，却搜不到内部文档和制品元数据。修法是修检索与版本发现。
- 环境缺口：评测沙箱里没有真实身份、网络或依赖。修法是给一个受控但真实的环境。
- 评测缺口：判据只检查了能不能编译、单测有没有通过，没核验权限、幂等和审计字段。这一块只能由人来补。
四类的修法互不替代。换一个更大的模型也许能让某一组任务暂时变好，但不会修掉后面三类问题。
顺手补一句它自己的证据强度
值得一提的是，第三方对这个手册的批评也很有价值：那四十六项改进是”改了多少处”的计数，官方并没有公布改动前后智能体的通过率变化；而且所有场景都跑在微软自家产品上，换到别的平台能不能复现，还得看那家平台的开发者提问方式是否相似、它的扩展有没有被智能体读到的路径。
所以这份手册更准确的用法是：把它当作方法模板，而不是当作结论。 它给的是”怎么问出真问题”的框架，不是”答案长什么样”。
三步上手
- 先跑一次裸测。 找一个你最熟悉的接口，写三到五条真实开发者的需求，让智能体从零开始做，不要给它额外提示。然后不要只看它写出来的代码，去翻它的执行轨迹——看它有没有检索、检索到了什么、有没有打开你的技能包或工具描述文件。
- 回过头写判据和闸门。 判据写清”什么才算做对了”，比如”使用的是当前版本的接口””失败路径必须留下审计记录””同一个幂等键只能产生一次退款”；闸门必须是真跑，编译通过、单测通过、真实沙箱返回都算。判据写完先自己复跑两遍，看结论会不会飘。
- 把每一次修复当成一次假设来验证。 改完文档或工具描述之后，用同一批需求重跑一遍。不重跑，你无法知道是哪个改动起了作用。
想顺着”智能体到底靠什么面工作”往下看，站内写过 MCP 协议今年的无状态改版（讲的是接口层怎么变）、Claude Code 的 Mods 机制（讲的是扩展能挂进哪一环），以及 DeepSeek 公开的智能体沙箱工厂（讲的是训练时环境怎么造）。这三篇和这份手册正好构成一条链：环境、接口、扩展面。
优缺点
优点：
- 它把”智能体用不好你的产品”从玄学变成了可测量的工程问题
- 承认评测本身会骗人，并给出判据与闸门两条硬要求，这一点比多数厂商文档诚实
- 明确了哪几个面是平台方能改的，责任边界清楚
- 给出了”没加载 / 加载没调用 / 调用了用错”这种可直接照抄的失败三分法
- 配套技能包能直接装进编程智能体，提问即答
缺点：
- 官方只公布了修复数量的计数，没有公布修复前后的通过率变化
- 验证场景全在微软自家技术栈上，外推性待检验
- 九类失败模式没有逐条公开拆解，落地时要靠自己的轨迹数据补
- 判据需要领域专家投入，这是整件事里最贵的一块，官方也承认这一点
适合谁，谁先别急
该认真读： 手里有 SDK、接口服务、命令行工具、MCP 服务端、技能包或插件的人；写这些工具文档的人；企业里负责把编程智能体引入研发流程的平台工程团队。你们控制着智能体能看到什么，所以你们是唯一能在源头修的人。
先别急： 只用现成工具、不做任何对外交付的个人用户——这套方法对你们没有落点；以及暂时没有能力跑真实沙箱的小团队，可以先从第 1 步的裸测开始，暂时不上判据工程。
三个替代做法
- 社区版评测集：用公开的代码智能体基准跑自家场景，胜在省事，代价是题目与你产品的真实用法有偏差。
- 只看单测通过率：最省成本，但要接受”实现和验收共享同一个错误”的风险，前面那个退款场景就是这么漏掉的。
- 纯人工评审：判据天然准确，代价是无法规模化，适合接口变更这种低频高风险的场景。
老达点评
第一，这份手册真正的价值，是把”模型不行”这个甩锅出口堵住了。它逼每一个平台方先回答一个问题：你的文档、你的接口描述、你的技能包，到底有没有被智能体读到并正确使用？这个提问方式的转变，比任何一条具体建议都重要。
第二，“评测能骗人”这段话，值得打印出来贴在墙上。 一个从来没编译通过的补丁拿到满分，一项无论真假都通过的检查——这不是理论风险，是所有自建评测体系的人都可能踩的坑。判据要能复现、闸门要真跑，这两条是最便宜也最容易被跳过的一步。
第三，它没有公布修复前后的通过率，这一点要记住。 四十六项改进是工作量，不是效果。做技术判断时，要分清”我们做了多少事”和”事情变好了多少”——很多团队内部汇报也栽在这里。
第四，在智能体越来越强的今天，这类”体验”工作会变成基础设施的一部分。 过去我们做搜索引擎优化，后来做无障碍与设备兼容，现在多了一样：让机器读懂你的产品。这件事现在做，成本还很低。
上手第一步
今天最省事的一步：挑一个你熟的接口，让编程智能体从零写一段调用代码，然后不看代码，只看轨迹——数一数它到底打开了几个你提供的资料。这一个小动作，就能告诉你自家那套”智能体友好”的说法，是真是假。
想顺着看下去，可以从 AI 智能体与自动化专题 和 AI 编程工具专题 翻起。之前写过的 Devin 把记忆写进 Git 仓库讲的是”智能体怎么记住教训”，Kimi Code 把权限拆成三档讲的是”怎么管住智能体”，可以和这篇连着看。
