九年前我设计了这套开放平台 API，九年后 AI 替我调用了它
先讲一件这周发生的小事。我让 AI 助手把一篇博客文章同步发到百家号，它调用了百家号开放平台的发布接口，一分钟后文章过审上线；然后我指出正文混进了一段博客站的导航文字，它撤回、改稿、重新发布，全程没让我碰键盘。这件事本身不稀奇——稀奇的是，它调用的那套 API，是我在 2017 年参与从零设计的。当年我作为百家号开放平台最早的产品经理之一，和团队一起定义了这套接口的鉴权方式、幂等逻辑和功能边界。九年后的今天，我自己成了这套接口的用户，而且是通过 AI 代理来用。
这个闭环让我想认真写一篇文章。不只为分享一套现成的 API 调用方案，更想聊聊这段经历里那些跨时代的部分：当年为"人"设计的接口约定，AI 用起来哪里顺手、哪里硌手；一个产品经理离开业务多年后，反过来被自己当年埋的设计决定"教育"了一次；以及当 API 的主要消费者从程序员变成 Agent，开放平台的产品设计逻辑应该怎么变。
一、2017：设计一套给"机构开发者"用的开放接口
2017 年 4 月我加入百度百家号时，它还是个初创项目。开放平台（后来叫灵渠）的出发点很朴素：媒体机构和第三方开发者不想登我们的创作后台，他们有自己的内容生产系统，希望内容能从自己的系统里直接发过来。所以我们要提供一套服务端 API——发布图文、发布视频、撤回、查询状态、拉评论和粉丝数据，一共十几个接口，覆盖内容全生命周期。
当时要回答的几个核心设计问题，今天回头看每一个都值得重新审视：
鉴权怎么做。最终方案是 app_id + app_token 的配对密钥：开发者注册后拿到一组凭证，每次请求带上，服务端校验配对关系。这个方案在 2017 年是主流——简单、无状态、够用。它没有 OAuth 的授权链路，没有细粒度 scope，token 不过期，泄露了只能手动重置。
幂等怎么保。内容平台最怕重复发布——网络重试、客户端 bug 都会导致同一篇稿子发两遍。我们用了最朴素的方案：origin_url 作为判重键，同一个原文地址再次提交，服务端直接返回上次创建的文章，不新建。这个决定在九年后的这个周，给我上了一课，后面细说。
同步还是异步。发布接口返回 errno=0 只是"受理成功"，真正的审核入库是异步的，几十秒到几分钟不等。当年这是给开发者文档里加粗提醒的坑；九年后的 AI 助手同样在这里被绊了一下——它以为返回成功就是发布成功，差点提前宣布胜利。
二、2026：AI 成了这套接口的"新用户"
时间快进到这个周。我把这套 API 的全部 18 个接口封装成了一个 AI skill：接口文档、错误码表、鉴权说明、踩坑记录，全部整理成 AI 可读的结构化知识，再配上一个 Python 客户端。然后我让 AI 助手"把这篇文章发到百家号"，它自己读文档、自己拼请求、自己轮询状态。
第一次端到端就成功了：发文、过审、上线，一分钟。但真正有意思的是接下来发生的三个问题——每一个都是九年前埋下的设计决定，在 AI 用户面前显出了新的棱角。
问题一：AI 不会带上下文，接口开始"说谎"
发布成功后我扫了一眼正文，发现结尾混着一行"← 返回博客列表 · 相关阅读：……"——这是博客站模板里的站内导航，AI 做跨平台格式适配时没剥干净，当成正文发过去了。
这个锅当然是适配流程的。但它暴露了一个更普遍的问题：人类开发者上传内容前会过一眼，AI 不会。接口对 content 字段的校验只查长度和合法标签，不查语义——九年前这是合理的宽容，九年后 AI 把这种宽容当成了"什么都能塞"。传统开发者的容错靠人肉自觉，Agent 的容错只能靠接口设计本身。如果这个接口今天重新设计，我会在文档里给 AI 用户加一段显式警告：正文请做站内元素剥离断言，或者干脆由服务端提供"纯净模式"白名单。
问题二：异步状态回流太慢，AI 误判"死路"引发连锁事故
改稿时 AI 走了标准的撤回-重发流程：调修改接口，返回受理成功，然后轮询状态。轮询了四分钟，状态一直停在"已撤回"，它判断这条路走不通，于是换了个策略——把文章重新发布了一遍。
结果两边都"成功"了。修改接口其实一直在生效，只是状态回流花了二十多分钟；而重发的那篇撞上了平台的消重机制，被判"与历史内容高度相似"，限流为仅主页可见。等我复核时，平台上同一篇文章存在两个版本，一好一坏。
这是这次闭环里最扎心的一课。异步接口的"慢"对人类开发者只是文档里的一句提醒——去喝杯咖啡回来再查；但对 AI 是行为分岔点：它会在自己的超时窗口里做出"失败"判定，然后执行兜底策略，而兜底策略（重发）在这个业务语境里恰恰是最危险的。九年后我作为用户付出的代价（消重限流），本质是九年前"状态最终一致、多久算正常没承诺"的设计决定的延期付款。如果重新设计，异步接口应该返回预估回流时间或至少给出 SLA 区间，让 Agent 的等待策略有依据。
问题三：三张封面图触发审核失败，文档没写的边界
第三个坑更小但更典型：封面传三张会触发图片处理失败且状态不自愈，传一张则稳定过审。这个边界在官方文档里没有写——封面参数说"0-3 张"，实际是"1 张稳、3 张看运气"。AI 第一版按官方示例老老实实传了三张，撞上了。
这类"文档与实现的暗差"是所有开放平台的老毛病。人类开发者撞上一次会在自己的笔记里记下来，社区论坛慢慢沉淀出民间文档；AI 撞上一次，如果没有人把结论写回它的知识库，它下次还会撞。传统开放平台的暗差靠社区消化，Agent 时代的暗差必须显式文档化——要么修实现，要么修文档，不能靠"用过的人都知道"来传递。
三、把踩坑变成资产：skill 化的 API 知识
上面三个问题最后都收敛成了同一个动作：把踩坑结论结构化地写进 skill。现在这套 skill 里，官方文档之外多了一层"实战层"——origin_url 必须每次唯一否则幂等命中返旧文章、封面宁少勿多、修改接口状态回流超过二十分钟属正常、同内容重发必撞消重、正文必须做站内元素断言。每一条都标注了实测日期和复现条件。
这个分层很关键。官方文档是"接口承诺"，实战层是"接口真相"。人类开发者两者都需要，但会自己区分；AI 需要你帮它把边界画清楚——它对文档的信任是全量的，文档没说的它默认不存在。所以给 Agent 准备 API 知识，比给人准备要多做一步：把"文档不会告诉你"的部分显式写出来，权重甚至要高于文档本身。
四、产品视角的三点反思
回到产品经理的本分，这次"自己吃自己的狗粮"给我三点实打实的反思：
1. API 的用户画像正在换血。2017 年我们画像里的开发者是机构里的程序员：会读文档、会调试、有耐心、有社区。2026 年这套接口的主要调用者变成了 Agent：读文档极快、零耐心、没有社区、对文档全量信任、超时即兜底。接口设计的优秀标准从"功能完备"变成了"防呆到底"——每一个模糊地带都会被 Agent 用最字面的方式执行。
2. 异步语义需要重新设计。异步不是问题，问题是异步没有时间承诺。人类能容忍"稍后生效"，因为人对"稍后"有经验感知；Agent 只能靠轮询窗口决策，窗口设短了误判，设长了低效。给异步任务加预估完成时间、进度查询、甚至 webhook 回调，是从"人类可用"到"Agent 可用"的关键升级。
3. 幂等键是双刃剑，方向要选对。当年用 origin_url 防重，保护的是"网络重试不产生重复内容"；但它同时制造了"重发即撞车"——同一篇文章修订后想重新发布，会被判重复。对人类这不是大事（改个 URL 就行），对 Agent 是隐蔽陷阱（它以为换 URL 是作弊，老老实实用原 URL 重试，反而被幂等逻辑吞掉新内容）。幂等键的选择，本质是在防重和允许修订之间选边，Agent 时代应该把"修订发布"作为显式能力设计进去，而不是让用户绕。
五、写给同样在做开放平台的产品经理
如果你今天在做一套对外 API，我的建议浓缩成三句话：
第一，把你的 API 文档写给两种读者：程序员和 Agent。给 Agent 的那份要多一节"边界与陷阱"，写清楚所有文档与实现不一致的地方——这些暗差在 Agent 时代不再是可容忍的瑕疵，而是必炸的雷。
第二，每个接口问自己一句：如果调用方零耐心、全信任、超时即兜底，这个接口的行为还安全吗？不安全的地方，就是你要补的防御性设计。
第三，尽快让 AI 真实调用你的接口跑一遍完整业务流。它能在一小时内暴露你九年没发现的语义模糊——我自己就是这么被教育的，代价是两篇文章和一个限流。
写在最后
九年前的我设计这套接口时，最远的想象是"机构开发者的服务器在调用它"。九年后的实际图景是：一个人对着聊天窗口说了句"把这篇发到百家号"，然后 AI 读完文档、拼好请求、踩完坑、自己把踩坑结论写进了知识库。
工具比设计者活得更久，而用户永远会以你想象不到的方式使用它。这大概是做产品最浪漫也最残酷的地方：你当年写下的每一个决定，都会在多年后的某一天，由某个你从不认识的调用方式来验收。这次验收，我给自己 2017 年的答卷打七分——能用，但给 Agent 用，还得迭代。
← 返回博客列表 · 相关阅读：16 条告警，一个摄像头，零真实威胁