标准化‘Intelligence’：三层元数据哲学
Source: Dev.to
请提供您希望翻译的正文内容，我将按照要求将其译成简体中文并保留原有的格式、Markdown 语法以及技术术语。谢谢！
Introduction
在之前的文章中，我们解释了为什么 AI 代理在依赖“vibes”时会失败，以及它们为何需要一个 “Cognitive Interface”。但是 Intelligence 在代码层面上是什么样子的呢？
如果让十位开发者向 AI 描述一个工具，你会得到十种不同的答案——有的侧重技术类型，有的写得文采斐然，还有的关注安全性。在 apcore 我们已将这种 “Intelligence” 标准化为 3‑Layer Metadata Stack。通过将技术语法、行为治理和战术智慧分离，我们为 AI 代理提供了对你的模块的 360 度全景视图。
Source: …
3 层元数据栈
我们将模块的“智能”可视化为一个从 必需 到 战术 的堆栈：
| 层级 | 目的 | 关键字段 |
|---|---|---|
| 第 1 层 – 核心 | 模块在 apcore 生态系统中存在所需的最小定义。 | input_schema、output_schema、description |
| 第 2 层 – 治理 | 定义代码的“人格”和“安全配置”。 | readonly、destructive、requires_approval、idempotent |
| 第 3 层 – 战术智慧 | 将人类经验直接注入模块的元数据。 | x-when-to-use、x-when-not-to-use、x-common-mistakes、… |
第 1 层 – 核心（必需）
- input_schema – AI 必须发送的内容。
- output_schema – AI 将收到的内容。
- description – 为 AI 的搜索引擎准备的简短“简介”。
目标： 精确。通过强制使用 JSON Schema Draft 2020‑12，我们提供一种任何 LLM 都能理解的通用语言。如果 AI 的语法不对，其他一切都无关紧要。
第 2 层 – 治理（行为）
readonly– 多次调用获取信息是否安全？destructive– 此操作是否会删除或覆盖数据？requires_approval– 是否需要人在运行前点击“是”进行确认？idempotent– 如果连接中断，AI 能否安全重试？
目标： 治理。安全和策略从提示转移到协议中，降低逻辑错误的可能性。
第 3 层 – 战术智慧（扩展）
x-when-to-use– 为代理的计划器提供正向指导。x-when-not-to-use– 提供负向指导，防止常见误用。x-common-mistakes– 开发过程中发现的常见错误。
目标： 战术智慧。人类经验直接编码在元数据中，避免将所有信息塞入单一描述字符串导致的认知负荷。
渐进式披露与代理阶段
apcore 使用 Progressive Disclosure 来保持 token 使用量低并确保推理可靠：
- 发现阶段 – 代理仅看到 Layer 1。
- 规划阶段 – 代理加载 Layer 2 以检查安全性和重试规则。
- 执行阶段 – 代理加载 Layer 3 以避免已知陷阱。
通过堆叠元数据，我们减少了 token 消耗，并显著提升了代理推理的可靠性。
示例：完整实现的 apcore 模块
class SensitiveTransferModule(Module):
# Layer 1: Core
input_schema = TransferInput
description = "Transfer funds to an external IBAN."
# Layer 2: Annotations (Governance)
annotations = ModuleAnnotations(
destructive=True,
requires_approval=True, # Safety gate
idempotent=True
)
# Layer 3: Extensions (Tactical Wisdom)
metadata = {
"x-when-not-to-use": "Do not use for internal account transfers.",
"x-common-mistakes": "Ensure the IBAN includes the country code.",
"x-preconditions": "User must be MFA authenticated."
}“Intelligence” 在代理时代并不是模型的魔法属性；它是模块的 工程标准。当你使用 apcore 3‑层哲学进行构建时，你实际上在打造一种 技能，任何 AI 都能以专业的精准度感知并使用它。
接下来
在下一篇文章中，我们将探讨 AI 幻觉的根本原因：“AI 集成中‘基于字符串’描述的终结。”
这是 apcore：构建 AI 可感知世界 系列的 第 7 篇。加入我们，共同规范 AI 交互的未来。