Agent Ontology Engine
让领域知识 成为可执行的系统。
AOE 把你的领域模型和知识编译成带版本的 Runtime。Agent 与应用查询它，拿到一份可检查的计划，并且只能通过声明过的 Action 改变状态。
AOE 是什么
当领域不只是一堆文档的时候。
如果你的领域里有具名的对象、对象之间的关系、需要可预期的检索，以及必须受控的操作，AOE 就用得上。你在自己的 Package 里声明这个领域：有哪些 Type 和 Relation，针对它们发布了哪些内容，以及 Agent 可以请求哪些 Action。
引擎把这些声明编译成不可变的 Snapshot 并对外提供服务。它只固定声明 schema 和运行时契约，其余一概不管。内部没有一份「业务类型清单」等着你复用，所以客服模型、菜谱模型和合规模型走的是同一条编译路径。
了解 Selection 如何工作 →{
"corpus": "com.example/support",
"query": "open incidents affecting the checkout service",
"topK": 8,
"projection": "core"
}一份 Selection Plan，你的应用可以记录它、比对它、为它写测试。
selected units- 命中了什么，以及加载顺序
score contributions- 每个 Unit 为什么排在这个位置
constraint decisions- 哪些约束生效了，作用在哪
relation expansion- 哪些关系被展开或排除
projection loads- 每个 Unit 取的是 summary、core 还是 full
budget use- 相对请求预算消耗了多少 token
snapshot identity- 由哪个 Release 和 digest 作答
由你拥有的 Package
Package 告诉 AOE 你的领域是什么。
原型阶段可以把四者放在一个仓库里；等到模型、数据、Provider 分属不同团队时，再分开发布。
什么可以存在，可以对它做什么
Type 与 Field、Relation 的方向与基数、各详细层级返回的 Projection、Retrieval Profile，以及 Agent 可以请求的 Action。这些声明本身就是数据，由引擎的 meta-schema 校验。
typesrelationsprojectionsretrievalactionspolicies 针对模型发布了哪些内容
Source Unit 与素材、Corpus 身份与兼容的模型区间、来源与许可证、可见性、评测夹具，以及签名后的 Release。一次构建把你的源文件变成不可变的 Snapshot。
unitssourceslicencereleasesdigests 外部世界从哪里接进来
来源目录、搜索 Provider、Validator、评测 Provider 或 Action Provider。Adapter 可以新增一个集成，但无法悄悄往你的模型里塞一个 Type 或 Relation，因此 Provider 始终是可替换的。
importersproviderspermissions Agent 真正安装的东西
Model、Corpus、Adapter，加上可选的 Tools 和可选的 Skill，组合成一个可部署的产品。Skill 负责教 Agent 怎么问得更好，它不授予任何能力，也绕不过 Action 的 Policy。
modelcorpusadapterstoolsskills 一次请求的旅程
从一份声明，到一次可靠的行动。
滚动查看领域在 Runtime 内部经过的四个边界。
-
词汇由你写下。
Model Package 定义什么是合法的对象与关系，Corpus Package 提供这些对象及其来源。引擎把两者都当数据读取，自己不携带任何领域。
- 输入
- types · relations · units
- 所有者
- 你的团队
- 产出
- 声明文件
-
声明变成可复现的构建。
Compiler 把 Model 与每个 Source Unit 组合，产出 Projection、索引、Manifest，以及锁定确切 schema digest 的 model.lock。同一份输入，得到同一份字节。
- 检查
- schema · relation · licence
- 产出
- Unit artifacts + index
- 保证
- 确定性
-
Runtime 只加载完整的 Snapshot。
Snapshot identity 绑定 Model、Corpus、Release 与 Digest。服务前 Runtime 会重新计算身份和内容，因此宿主能确认这份 Release 是不是 Corpus 期望的那一份、以及它是否完整未被篡改。
- 身份
- tenant · corpus · release
- 证明
- manifest + content digest
- 状态
- 不可变
-
读取与写入是两份独立契约。
Query 返回带约束与证据的 Selection Plan。Action 从模型声明出发，依次通过 Principal、Capability、前置条件、幂等性与 Policy 检查，先给出 Effect Plan，等到所需审批通过后才真正执行；运行记录与证据追加进 Event Store。
- 读取
- SDK · MCP · HTTP
- 规划
- 可解释 + 有预算
- 写入
- Policy 门控
选择你的边界
把 Runtime 放到工作已经发生的地方。
同一份 Model 与 Corpus，可以嵌入进程、通过 MCP 挂载到 Agent，或部署在 HTTP 服务之后。Query、Plan 与 Action 契约保持不变。
阅读接入指南 →import { AoeClient } from '@aoe/sdk';
const aoe = new AoeClient({
snapshot: './dist/snapshot',
model: './model',
});
const plan = await aoe.query({
corpus: 'com.example/support',
query: 'open incidents affecting checkout',
topK: 8,
});
// plan.selected, plan.constraints, plan.snapshotAOE_CORPUS_DIR=./dist/snapshot \
AOE_MODEL_DIR=./model \
bun packages/mcp-server-core/src/index.ts
# tools the Model Package exposes to the agent
aoe_query({ query: "open incidents affecting checkout" })
aoe_plan({ query: "...", budget: { tokens: 4000 } })
aoe_act({ action: "resolve", target: "INC-2041" })curl -X POST https://runtime.example/v1/query \
-H 'Authorization: Bearer $AOE_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"corpus": "com.example/support",
"query": "open incidents affecting checkout",
"projection": "core"
}'
# → SelectionPlan + snapshot identity + digest大家用它做什么
只要 Agent 需要叫得出你的对象的名字。
下面这些场景需要的是同样三件事：应用与 Agent 共享一套词汇、内容有可追溯的来源、写操作始终在 Policy 之下。
- 01
客服助手
Incident、Service、Team、Release 以及它们之间的关系，让助手顺着影响面走，而不是从工单文本里猜。
它能回答的问题 哪些未关闭的 Incident 影响了 checkout，负责人是谁？
- 02
合规审查
控制项、证据与例外都处于带版本的 Release 之下，审查结论可以引用它读到的那一份确切 Snapshot。
它能回答的问题 本季度哪些控制项还缺证据？
- 03
运维知识库
Runbook 与流程作为带前置条件的 Unit，其中有风险的步骤是声明过的 Action，而不是让 Agent 现场发挥的说明文字。
它能回答的问题 回滚流程是什么，我有权限执行吗？
- 04
数据目录
数据集、Owner、血缘与访问规则，通过你配置的 Retrieval Profile 取回，而不是一个你无法检查的相似度分数。
它能回答的问题 哪些数据集含客户数据，谁来批准访问？
- 05
设计系统规范
参考用的 Frontend Design Package：797 个 Unit 的模式、反模式与规则，供 Agent 在写界面代码时查阅。
它能回答的问题 这个组件里有什么破坏了键盘可达性？
五分钟路径
三条命令，得到一个可验证的 Runtime。
引擎仓库自带一个小示例，让你在创建自己的领域之前先把整条路径看一遍。
- 01
安装引擎
克隆仓库并用冻结的 lockfile 安装。
git clone https://github.com/kernary-aoe/aoe-engine.git cd aoe-engine bun install --frozen-lockfile - 02
构建示例
Model 路径必须显式写出，因为示例词汇属于示例 Package，不属于 AOE Core。
bun scripts/build-atom-dirs.ts \ --src examples/hello-world/primes/sources \ --out examples/hello-world/primes/compiled \ --model compat/prime-v1-model \ --corpus org.example/hello-world \ --release 2026-08-31 - 03
连接客户端
挂载你刚构建的同一份 Snapshot 与 Model。SDK 与 HTTP 暴露的契约完全一致。
AOE_CORPUS_DIR=examples/hello-world/primes/compiled \ AOE_MODEL_DIR=compat/prime-v1-model \ bun packages/mcp-server-core/src/index.ts
常见问题
你可能想问。
01 这和把文档塞进 Prompt 或向量库有什么区别？
Prompt 和向量索引存的是文本，返回的是按相似度排序的片段。AOE 存的是编译后的领域：带类型的 Unit、有向 Relation、模型定义的 Projection，以及声明过的 Action，全部处于带版本的 Snapshot 之下。Query 返回的 Selection Plan 记录了命中什么、哪些约束生效，所以你可以记录它、在两个 Release 之间比对它、为它写测试。
02 AOE 会强加一套本体给我吗？
不会。引擎只固定声明 meta-schema 和稳定 IR。Type、Field、Relation、Retrieval Profile 与 Action 都来自外部 Model Package。注册表里的 Frontend Design、Security、Backend 和移动端语料都是参考 Package，你可以读它、替换它，也可以完全不用。
03 「可验证 Snapshot」到底保证了什么？
每个 Release 都带有绑定 model.lock 的 Manifest 和内容摘要。服务之前 Runtime 会重新计算身份与内容，宿主因此能确认这份 Snapshot 是 Corpus 期望的那个 Release、并且是完整的。文件一旦变化，这次 Release 就是失败的，而不会被静默地提供出去。
04 Agent 只能读，还是也能改？
都可以，但走两份独立契约。Query 与 Plan 是只读的。Action 会校验输入、Principal、Capability、前置条件、Provider 绑定、副作用类别、幂等性与 Policy，先返回一份 Effect Plan 而不执行任何东西；执行要等到所需审批通过，运行记录与证据随后追加进 Event Store。默认是拒绝。
05 现在有哪些客户端可以接入？
任何支持 MCP 的 Agent 都能直接挂载一个 Package。应用可以在进程内嵌入 SDK，或从别的服务调用 HTTP Transport。三者共享同一套 Query、Plan 与 Action 契约，所以选哪个是部署问题，不是语义问题。
06 维护一个 Package 的成本是什么？
编辑源文件，然后重新构建。索引、Manifest、model.lock 这类生成文件从不手工编辑，构建会原子地重新生成它们，摘要与来源信息因此始终可信。Model 与 Corpus 各自带版本，Corpus 会声明自己面向的模型区间。
07 AOE 可以上生产了吗？
AOE 目前是 0.2，使用 Apache-2.0 许可。文档里描述的 Package、Snapshot、Query 与 Action 契约都是当前版本；这个站点上的注册表是静态的发现页面，不是托管的 Registry 服务。在依赖某个契约之前，请先读发布日志。