“认知接口”：超越 UI 与 API

几十年来，软件工程一直专注于两个主要的接口：

用户界面 (UI)：针对人类感知进行优化——视觉化、直观且具有交互性。
应用程序编程接口 (API)：针对机器感知进行优化——结构化、强类型（REST、gRPC）且具有确定性。

但随着我们进入自主 Agent（Autonomous Agents）时代，一个巨大的鸿沟出现了。AI Agent 既不是人类，也不是传统的程序。它是一个认知调用者（Cognitive Caller）。它不仅需要知道该访问哪个端点；它还需要感知它即将调用的代码的意图、行为和约束。

在 apcore 系列的这第二篇文章中，我们将探讨认知接口（Cognitive Interface）的兴起，以及为什么它是现代软件栈中不可或缺的第三层。

感知鸿沟

传统的 API 是为编译器和人类开发者构建的。当开发者使用 API 时，他们会阅读文档，理解边缘情况，并编写代码来处理这些情况。当一台机器通过 gRPC 调用另一台机器时，它依赖于严格的二进制契约。

AI Agent 的运作方式则截然不同。 它们通过语义镜头来“感知”你的系统。如果你的 API 缺乏认知接口，Agent 就不得不对上下文产生“幻觉”。

要做到真正的 AI 可感知，一个模块必须经过认知的三个阶段：

感知： “我看到存在一个声称处理‘支付’（Payments）的工具。”
理解： “我理解这个工具是破坏性（destructive）的，需要 mfa_approval（多因素认证审批），且不应被用于超过 500 美元的金额。”
执行： “我可以生成正确的 JSON Schema，并且如果余额不足，我能处理返回的结构化错误。”

为什么 Swagger/OpenAPI 还远远不够

许多开发者会想：“我已经有 Swagger 文档了，那不就是认知接口吗？”

并非如此。

Swagger (OpenAPI) 是为人类阅读和工具生成客户端 SDK 而设计的。它缺乏 AI 做出自主决策所需的行为语义。

Swagger 会告知 Agent 某个特定端点是“昂贵”的还是“缓慢”的吗？
它会解释“常见错误”或“什么时候不该使用”这个工具吗？
它会提供关于如何从 403 错误中恢复的“AI 专用引导”吗？

一个真正的认知接口，正如 apcore 标准所定义的那样，提供了一个包裹在技术 API 之上的语义层。

认知接口的架构

在 apcore 中，我们通过渐进式披露（Progressive Disclosure）系统来实现认知接口。我们不会一次性用所有细节淹没 LLM 的上下文窗口。

1. 发现层 (description)

一个短小的、约 100 字符的字符串。这是 AI 用来寻找候选工具的“索引”。示例：”通过 ProtonMail API 发送加密邮件。”

2. 规划层 (annotations)

结构化的元数据，告知 AI 代码的“性格”。示例：readonly=False, destructive=True, requires_approval=True。

3. 认知层 (documentation)

详尽的、支持 Markdown 的文档，AI 只有在为任务选定该工具之后才会阅读。这包括使用示例、业务约束和陷阱。

# apcore 中的认知接口 (Python)
class FinancialTransferModule(Module):
    description = "在内部账户之间转账。"

    documentation = """
    ## 约束
    - 单笔转账上限：10,000 美元。
    - 上下文中需要具有 'finance_admin' 角色。
    - 后置条件：两个账户余额将原子化更新。

    ## 常见错误
    - 请勿用于外部电汇；请改用 `executor.wire.transfer`。
    """

    annotations = ModuleAnnotations(
        destructive=False,
        requires_approval=True, # 关键的认知“停止标志”
        cacheable=False
    )