过去十年做开放平台，我们默认的调用方是人类开发者：会通读文档、会 Google、会照着报错一点点试、会凭经验补上文档里没写清楚的部分。整套设计——文档怎么写、接口怎么拆、错误怎么报、权限怎么分——都是围绕「一个有经验的人会怎么用」来优化的。

现在调用方在变。越来越多的集成不是人坐下来读文档写出来的，而是把一个文档 URL 扔给 Agent，让它「按这个需求，把整个集成应用做出来」。我在得物国际开放平台（POIZON Open Platform，下称 POP）上，把 Agent 真正放上去端到端跑过一轮之后，最直接的感受是：传统开放平台的很多设计假设，在 Agent 面前不是「差一点」，而是直接失效。

要理解为什么失效，先得换掉一个心智模型。这里说的 Agent，不是泛指所有聊天机器人，而是「拿到开放平台文档后，要自己生成代码、调用 API、完成集成任务」的那类开发型 Agent：

在开放平台集成这个场景里，Agent 不应被当成「更聪明的用户」，而应先被当成「有限上下文的代码生成器」。 它不靠经验推断背景知识，只能消费被显式表达的语义；你没写出来的，它就当不存在；它也没有「读完整站再动手」的耐心和上下文窗口。

由此往下推：Agent 的瓶颈不在「它聪不聪明」，而在「它要花多大代价、能不能不靠人，把正确的语义凑齐」。 下面衡量、重做、验证三段，都是围绕这一句展开。

1. 衡量：旧指标不变，但头号指标在迁移

先说不变的。一个成熟开放平台的指标体系其实已经很完整，而且 AI 时代依然成立：

  • 北极星：开放平台价值贡献占比（通过平台产生的 GMV / 收入 ÷ 总业务价值）——回答「开放平台为什么存在」。
  • 开发者生命周期：注册 → 激活（首次成功调用，对标 Stripe 的 Time to First Call）→ 留存 → 升级转化 → 头部集中度。留存曲线下滑、头部贡献超过 80%，都是生态早期衰退的信号。
  • 接口与稳定性：调用成功率、P50 / P99、4xx（开发者侧）vs 5xx（平台侧）分布、限流触发率、MTTR、SLA 达标率。
  • 开发者体验：NPS、文档可读性、工单响应、社区活跃度。

这些不会因为 AI 来了就过时——它们衡量的是「生态健康」，和调用方是人还是 Agent 无关。

AI 时代真正新增的是两件事。

第一，加一层「AI 友好度」维度。 它和体验指标平行，但量的是机器消费的顺滑度：结构化文档覆盖率（OpenAPI 完整覆盖的接口比例）、MCP 接口暴露率、Skill 文件完整度、错误码机器可解析率（结构里有没有 error_code / error_type，Agent 的自动重试 / 降级全靠它）。还有一个很锋利的代理指标：Agent 调用成功率 vs 人工调用成功率的差值。在权限、环境、任务输入基本一致的前提下，这个差越大，越说明你的接口里有大量语义仍然靠人类经验在补。

第二，也是更关键的：头号指标本身在迁移。 传统头号指标问的是「人能不能调通」；AI 时代要问的是——

把一个 URL 扔给 Agent，它能不能不靠人、端到端把这个集成做出来？

我把这个新头号指标叫 TSR（Task Success Rate）。它不是把旧的「调用成功率」改个名，它的三个设计决策，每一个都是被实测打出来的。

1）测量单位必须是端到端场景，不是原子接口。 这点我交过学费：第一次测的时候按「单个接口在只给文档的条件下能不能调通」打分，结果在那版 doc-only 单接口测试里，POP 的签名、核心写接口全是 100%——看起来很好，实际毫无信息量。因为真正难的地方根本不在单接口：是一百多个 API 里到底选哪个、是 skuId 这种字段要在三四个接口间正确流转、是 price 到底传分还是元。这些只在端到端链路里才暴露。单接口能调通，只能证明原子接口可调用，证明不了 Agent 能完成一个真实集成任务。

2）成功率之外，要单立一条正交轴：token 成本（tokens-to-success）。 这条最容易被忽略，但它是某些改造价值的唯一可见度量。一个真实例子：POP 文档站（open.poizon.com）是 JS-SPA 渲染，只会 HTTP GET 的 Agent 抓回来是个空壳，参数表读不到，只能退化成「截图 + OCR」——同一个任务，token 直接十倍起。把文档做成可 fetch 的纯文本接口，这个改造几乎不动成功率，却能把 token 砍一个数量级。如果你只盯成功率，这种改造在仪表盘上是隐形的。

3）打分不要 0/1，要自主度阶梯。 我把恢复方式分级：完全自主跑通 / 点破一句话就行 / 得把代码喂给它才行 / 喂了也救不回来。头号 TSR 只数「完全自主」那一档，但整条阶梯的直方图才是真正的诊断剖面——它能区分「只差一句提示」和「喂了码也没用」这两种完全不同的严重度。卡在哪一级，对应哪一层坏、该改哪——打分这个动作本身就是诊断。

2. 重做：Agent-Friendly 的四层

要把 TSR 拉起来，得从下往上动四层，地基到表层——下层不动，上层怎么包都是给烂路铺地毯：

  • Layer 1 · 原子能力（API Quality） — 地基，上层封装都继承它
  • Layer 2 · 语义表达（Semantic Clarity） — 补字段名与业务语义的 gap
  • Layer 3 · 文档架构（Navigation） — 解决 Agent 上下文有限
  • Layer 4 · 接口协议（Callable Interface） — 消除对浏览器操作的依赖

2.1 Layer 1 · 原子能力（地基）

三件事，每件都对应一个「人能容忍、Agent 不能」的点：

  • 参数命名全平台一致。 人能脑补 create_time 和 created_at 是一回事，Agent 会直接构造错字段。同一个语义概念，全平台只能有一个名字。
  • 错误返回必须结构化。 不能只甩一个 message 字符串。Agent 遇错时要自动决定是「换参数重试」还是「放弃这条路」，这个判断的前提，就是错误体里有机器能读的 error_code / error_type / hint。
  • 写接口天然幂等，幂等键语义显式。 Agent 编排多步操作，失败概率远高于人工，幂等是它安全重试的地基。POP 的寄售写接口（enterprise-stock-apply/add）就没有幂等键——Agent 一旦在这步失败重试，就重复挂单。

那存量那些字段乱七八糟的老接口怎么办？ 这是任何有历史包袱的平台都绕不开的问题。命名一致是对新接口的硬要求；存量接口直接改名是 breaking change，动不得。务实的做法分两步：

  1. 先立一套规范词表（canonical vocabulary），新接口一律对齐，先止血、不让混乱继续增量。
  2. 老接口不在原地改，而是在「Agent 消费的那一层」做归一化。 两条路：轻的，用 Layer 2 的避坑说明 + 术语表把「这个字段其实等于那个规范名、单位是什么」显式标注出来（纯内容、零风险、不碰接口）；重一点的，在对外的文档 / IR / MCP 层加一层别名映射，把混乱的真实字段翻译成统一词汇再暴露给 Agent。原始接口保持不动，Agent 看到的是一套干净的语义。

换句话说，历史包袱不靠「重写接口」解决，靠「在暴露层补一层翻译」解决——这也是为什么下面 Layer 2 的纯内容改造 ROI 最高。

这层为什么是地基？因为无论上层是 CLI 封装、MCP Server，还是 Agent 自己读文档，最终调的都是同一组原子 API。接口形式还在收敛，但原子 API 的质量是不会过时的投资。

2.2 Layer 2 · 语义表达（最便宜、ROI 最高，P0）

这一层全是纯内容改动，没有工程依赖，却最直接地影响成功率。核心是把「人靠经验能推断、Agent 从字段名推断不出来」的陷阱，显式写出来。

最典型的三类陷阱（都是真实踩过的）：

  • price 字段名不告诉你单位是分还是元——$154.00 要传 15400，传 154 就是错一百倍。
  • requestId 不读描述，猜不到它是幂等键。
  • oldQuantity / quantity 是快照值，不是增量——字段名完全不透露这一点。

做法很轻，三件：

  1. 每个接口底部加一个「踩坑说明」区块，把上面这类语义陷阱逐条写明。
  2. 一个枚举值集中页。 所有枚举（订单状态、币种、国家码、承运商）集中维护——绝不能散落在各接口描述里。因为 Agent 在为某一个接口生成代码时，根本看不到别的接口页里那段枚举定义。
  3. 每个接口配 2–3 个错误处理示例。 集成代码里约三成是错误处理，而平台特有的报错行为，Agent 完全没法凭空推断。

2.3 Layer 3 · 文档架构（解决上下文有限，P0）

真人可以通读一百多个 API 再决定怎么走；Agent 需要在加载之前就知道「我这个场景只读这 5 个」。所以组织单元要从「按 API」换成「按场景」。

这里有个关键、也最容易被忽略的点：一张通用的字段流转图，对 Agent 是误导。 因为复杂平台里同一个关键字段（比如 skuId）可能有好几个来源接口，到底用哪个，取决于商家的业务上下文，不取决于接口本身。一张大图把所有可能性画在一起，对 Agent 反而是语义歧义。

正解是三层场景化 Playbook：

  • 第一层：场景入口——「我是哪种商家」（有品牌货号手动挂单 / 已有 skuId 批量调价 / 接 ERP 自动同步）。
  • 第二层：场景内的字段流转——这一条路怎么走，字段来源和去向唯一确定。
  • 第三层：链回各接口详情页。

关键原则：场景内的流转必须唯一确定，不能让 Agent 在 Playbook 内部还要做「用哪个接口取 skuId」的选择。如果有多个可能来源，就拆成多个 Playbook。一个具体的样子（品牌货号 → 挂单）：

步骤 动作 入参 产出
Step 1 按货号查商品 articleNumber、region skuId
Step 2 查推荐定价 skuId、biddingType、currency 参考价
Step 3 提交挂单 skuId、price、quantity、requestId（新 UUID） 挂单号

每一步入参从哪来、产出什么，全部钉死，不留歧义——这正是「把决策前置到文档架构里」的意思。

2.4 Layer 4 · 接口协议（让机器直接消费）

最后一层，是把文档和能力变成机器能直接消费的形式。这里我走过一段弯路，也是这篇里我自己推翻过的一个设计：

我最初想自建一套专有的 fetch 接口（类似 /docs/api/index.json + /docs/api/{id}.md），让 Agent 一次 GET 拿全。后来推翻了——与其发明一套只有自己懂的专有格式，不如骑在正在收敛的生态约定上。 自造格式没有发现机制、没有现成的消费方；对齐标准才有网络效应。

所以现在 POP 的方向改成了优先对齐 Stripe 那套已经成形的约定。这里不是说要照抄 Stripe 的产品形态，而是先复用 Agent 已经可能识别的入口和文件约定，少发明一套只有自己懂的格式：

  • 给现有文档页加 .md 镜像：URL 后缀加 .md（apiDetail/170 → apiDetail/170.md），随接口配置自动生成。任何只会 GET 的 Agent 一次就能拿到纯文本，不必为它单独造一套索引 API。
  • llms.txt（参考 docs.stripe.com/llms.txt，部署在 open.poizon.com/llms.txt）：给 Agent 的总入口，登记关键路径与 API 索引，且 API 部分随配置自动更新。
  • Agent Skills 标准：/.well-known/skills/index.json + SKILL.md（同样对标 Stripe），让 Agent 用一行 npx skills add https://open.poizon.com 装上平台技能。
  • 术语表 glossary.md（中文术语 / 官方英文 / 一句话定义）：用一张表解决多语言一致性，成本远低于把全量文档翻译四遍。

再往上才是 OpenAPI Spec 与 MCP Server——但它们的地基，正是上面这套「对齐标准、随配置自动生成」的内容层。

这一层的顺序也极其重要。 把四层按「成本 × 指标」摊开：

优先级 层 动作 成本
P0 L2 每接口踩坑说明 低（纯内容）
P0 L3 场景化 Playbook 低（纯内容）
P1 L2 错误处理示例 低（纯内容）
P1 L4 .md 镜像 / llms.txt / skill 中（配置 + 后端）
P1 L1 错误码结构化 中（接口改造）
P2 L4 OpenAPI / MCP 高（系统工程）

两项 P0 全是纯内容、零工程，应该立刻做；工程项要等内容改造验证出效果再投。 一上来就 all-in MCP，是把工程资源压在没验证的方向上——这恰恰是「API 是地基不是天花板」这句话的实操含义。

3. 验证：把框架变成一个能跑的分

方法论谁都能写，难的是证明改造真的有用、且能拿出数字。所以我把上面两套（指标 + 四层）做成了一个开源的行为性 benchmark（open-platform-agent-readiness-benchmark）：从一个 URL 起跑，让 Agent 端到端做集成，卡住了按「提示阶梯」逐级喂提示，再按它在哪一级恢复来打分。两个用途——横评不同平台（Stripe / Shopify / 微信 / 飞书 / 得物），和量自家改造前后的增量。后者才是简历上「shipped & measured」那一栏的来源。

做这个 benchmark 的过程，本身就是几个被实测逼出来的设计决策：

  • 从「原子接口」改成「端到端场景」（同前：单接口 doc-only 全 100%，毫无区分度）。
  • 头号指标从 FPSR 改名 TSR：原来叫 first-pass，字面是「第一次过」，定义却是「不靠人工」，名实不符；而且 Agent 会自己循环纠错。「要不要靠试错」这件事，挪到成本族的 iterations-to-success 去量。
  • 加 token 成本轴（它是 L4 改造价值的唯一可见度量）。
  • 0/1 改成 A0–A4 自主度阶梯（打分即诊断）。
  • 场景集是冻结的「四件套」：意图 / golden 全链路轨迹 / 步骤断言 / 提示阶梯——这四样才是 benchmark 的本体，而不是分数。

要强调的是：这套评分标准本身一直在迭代（目前到 v0.3）。上面这些决策没一个是一开始就想清楚的，全是一版版被实测推翻、改出来的；所以它更像一个会持续长大的诊断工具，而不是一锤定音的排行榜——我也会随着在更多平台上跑、随生态约定变化继续动它。

真跑下来，最值钱的不是那个分，是它逼出来的几个事实——而且每一个都精准落在某一层：

  • POP 文档站 JS-SPA，静态 GET 返回空壳——只会 GET 的 Agent 连参数表都读不到（L4 缺口）。
  • POP 自带的签名示例自相矛盾：拿文档给的输入，复现不出文档声称的签名结果；忠实照文档做 = 0% 通过（L2 缺陷，而且是最伤信任的那种）。
  • 核心寄售写接口没有幂等键（L1 缺口）。
  • 还有一条打在我自己脸上：第一版我把「必填参数」直接喂进了任务，于是测出 100% 通过——「假绿」在我自己的测量装置里复现了。这条逼出 benchmark 的两条威胁防线：防 harness 泄题、防钓提示。否则你测的只是自己喂进去的答案。

4. 收尾：真正的门槛不在技术

把三段连起来：传统开放平台优化的是「人读文档、人调试」的体验；AI 时代优化的是「Agent 不靠人就能把集成做出来」的概率。

  • 衡量：旧指标全留，加一层 AI 友好度，并把头号指标从「人能不能调通」换成「Agent 端到端 TSR + token 成本」。
  • 重做：从下到上四层，先做纯内容的两项 P0，再投工程，记住 API 是地基不是天花板。
  • 验证：用行为 benchmark 把「改造有没有用」变成可复现的分，顺便逼出最该改的那几个洞。

但最后要讲一个不浪漫的现实：真正卡住这件事的，往往不是技术。 P0 全是纯内容改动、零工程依赖，照样可能推不动——那是组织动力问题，是「谁为开发者体验背 KPI」的问题。而最硬的「改造前后」证据，依赖一个真实可执行的测试环境；如果平台没有稳定沙箱，这条最有说服力的曲线，在平台层面就会先被环境卡住。

衡量、重做、验证三件事都能写成方法论；但能不能落地，最后考的是组织愿不愿意为「看不见的调用方」投入。这才是 AI 时代开放平台真正的分水岭。