2024年，企业平均每个API要配47页文档。但当你把这套文档扔给AI Agent，它还是会问出灵魂问题："这个接口能删数据吗？需要老板审批吗？出错了我该找谁？"
人类程序员读文档靠经验补全，AI没有这种直觉。它要么瞎猜，要么干脆罢工。
这就是apcore团队提出的「认知接口」（Cognitive Interface）要解决的问题——不是让API更好读，而是让AI能「感知」代码的脾气。
API文档的幻觉陷阱
Swagger/OpenAPI写了十几年，人类开发者用着挺顺手。但apcore的工程师发现，这类文档天生带着一个盲区：它告诉AI「能做什么」，却不告诉AI「做了会怎样」。
举个例子。一个转账API的文档可能写满参数类型、返回格式、错误码列表。但AI真正想知道的是：这操作会不会把钱转丢？要不要先问财务总监？失败了能撤回吗？
这些信息散落在注释、内部Wiki、老员工的脑子里。AI没有权限翻这些，只能「幻觉」——用概率推测最可能的答案。
apcore把这种成本叫「翻译税」（Translation Tax）。企业现在花几千小时写工具包装层、调系统提示词，本质上都是在帮AI补课。
三层递进：让AI像人一样「扫一眼再细看」
认知接口的设计借鉴了人类的工作习惯：先扫标题，再看摘要，最后翻详情。
第一层是100字符的「索引卡」。比如「通过ProtonMail API发送加密邮件」。AI靠这个快速匹配工具，不浪费上下文窗口。
第二层是结构化元数据，相当于代码的「性格标签」：会不会改数据（destructive）、要不要人工审批（requires_approval）、能不能缓存结果（cacheable）。
第三层才是完整文档，Markdown格式，带约束条件和常见错误。AI只有选定工具后才会读这部分。
apcore管这叫「渐进式披露」（Progressive Disclosure）。类比一下：你去餐厅点菜，菜单第一行是「宫保鸡丁·辣·含花生」，足够你做决定。配料表和过敏原提示印在小字背面，需要再翻。
现在的API文档把配料表放在最前面，AI读完已经忘了菜名。
代码里的「认知刹车片」
看一段apcore的Python示例。一个内部转账模块的注解里，requires_approval=True被标注为「关键认知停止标志」。
这不是装饰。当AI Agent规划任务流时，这个标签会强制触发审批节点——就像汽车里的限速提醒，不是建议，是硬拦截。
文档里还明确写了「不要用这个做外部电汇，去找executor.wire.transfer」。这种「负向指令」在传统API里几乎不存在，但对AI决策至关重要。
apcore的工程师认为，认知接口的核心不是传递更多信息，而是传递「决策所需的上下文」。人类靠经验补全的部分，AI需要被显式告知。
这解释了为什么Swagger不够。它是给编译器和人类看的契约，不是给「认知调用者」看的地图。
谁在为「翻译税」买单
企业AI集成的现状是：每接一个新API，工程师要写一套提示词工程，教LLM怎么调用、什么能碰、什么会炸。API版本一更新，这套工程可能全废。
apcore想把这个成本压到零。如果API自带认知接口，AI Agent可以自主发现、自主决策、自主报错。
这有点像HTTP协议统一了网页传输。在HTTP之前，每个服务器都有自己的规矩。认知接口想做的是AI时代的HTTP——不是技术协议，是「预期协议」。
当然，标准能不能成，要看多少厂商愿意把自己的「代码性格」暴露出来。有些公司可能觉得，让AI太容易看懂自己的系统，等于把底牌亮给竞争对手。
但如果认知接口成为默认选项，拒绝接入的API可能会像没有SSL证书的网页一样——能用，但AI Agent会优先绕过。
apcore的博客评论区有个问题被顶到了最上面：「如果两个模块的认知接口互相矛盾，AI该听谁的？」团队还没回复。这或许是下一个要填的坑。
热门跟贴