SDK

Nimi SDK 是面向应用的接入层。它给应用一个受支持的方式来使用 Runtime、Realm、世界语义、AI Provider 接入面、Scope、Mod 和共享类型，而不需要 import 任何私有内部模块。

如果你在基于 Nimi 构建产品，SDK 是你应该首先关注的边界。遵守 SDK 边界的应用在 Runtime 或 Realm 内部演化时仍然能跑；绕过它的应用每一次内部演化都会变成 breaking change。

本章节包含

跨域的术语表解释「面板」、「边界」等词的含义。

Nimi 有多个权威域。Runtime 拥有执行；Realm 拥有语义真相；桌面端拥有原生外壳行为；Cognition 拥有独立的记忆与知识权威。应用代码需要一个稳定的方式使用这些域，而不与它们的私有实现耦合。

SDK 就是这个边界。这个边界在 SDK kernel 中以 S-BOUNDARY-* 与 S-SURFACE-* 系列规则被认可。

SDK 拆成命名子路径，每个子路径都有自己的面板合同：

应用通常会从多个子路径 import。这种切分的目的，是让每个子路径在自己的合同下独立演化，而不互相污染。

规范区分已认可的核心面板和已定义但实现尚未完成的面板。公开文档不会把仅定义、尚未实现的面板说成完全可用的产品。

实用判断：当某页把一个面板称为「合同级」（contract-level），合同是已认可的；当称为「面板形状级」（projection-only，spec 中的术语），面板形状已定义但实现尚未当作完整公开产品。

设想你在写一个应用，需要让 Runtime 做一次生成、读世界真相，以及对 Realm 更新做出反应：

从 sdk/runtime import。发起生成请求并按流式合同消费流式响应；详见 Runtime 工作流与多模态。
从 sdk/realm import（或 sdk/world，如果你需要组合后的世界读）来读世界真相。不要 import Realm 内部 — SDK 只把你的应用被允许看到的部分暴露给你。
如果应用需要授权和目录读写，从 sdk/scope import。
仅当你在做宿主注入的 Mod 面时，才从 sdk/mod import；否则这条子路径不属于你的代码。
共享类型从 sdk/types，是其他子路径间稳定的拼接积木。

最终结果是一个没有 import 任何私有路径的应用。当 Runtime 或 Realm 内部演化时，只要 SDK 合同保持稳定，你的应用就能继续工作。

设想重构期间一个开发者想：「我直接从 runtime 包 import 这个 helper 就行了；SDK 没问题，但又多了一层。」这个 import 正是 SDK 边界禁止的。

如果违规落地，会出两件错事：

把违规挡在代码评审是让应用接入保持诚实的方式。SDK kernel 的 import 边界表是「什么允许、什么不允许」的权威清单。