SDK 架构边界

SDK 边界旨在为应用集成提供稳定、明确且可预期的契约保障。它不仅是一套便利的 API 封装，更是隔离应用业务层与平台各底层域（Runtime、Realm、Desktop）私有实现的防护线。

相关的核心设计规范遵循 S-BOUNDARY-* 与 S-SURFACE-*。

核心边界准则

使用官方公开导出：App 必须通过 SDK 官方公开的导出子路径消费能力，避免跨层直接引用 Runtime 或 Realm 的私有内部模块。
维护单一权威事实源：SDK 各公共接口是对底层能力的映射与表达，不得隐式篡改或重定义 Runtime、Realm 或 Desktop 的底层权威状态。
严格遵循规范发布：包文件的物理存储路径、内部源码目录结构或临时的文档说明，均不直接构成公共 SDK 的稳定性承诺；所有对外承诺必须在规范中正式登记并通过受管方式导出。

跨层侵入与边界违规在初期往往看似代价极低——引入一个深层内部的辅助函数、绕过标准 Client 直接发起裸网络请求，在局部短时间内似乎都能正常工作。

然而，随着项目演进，此类绕过行为会演变成难以维护的架构负债：应用逻辑与底层私有细节紧密耦合，一旦底层进行正常的重构或性能优化，应用就会意外破坏或失效；同时，绕过标准 Shell 还会丢失关键的安全上下文校验与审计凭据，导致多端协同出现隐蔽的状态漂移。

开发者在实现业务逻辑时需要一段数据转换或格式化逻辑，发现 runtime/internal/** 内部恰好有现成实现，便直接将其 import 进应用工程：

潜在风险：底层包的内部实现随时可能重构、更名或废弃，没有任何向后兼容保证。
正确应对方式：
- 评估该逻辑是否属于应用自有的通用业务工具：若是，应当在应用内部自建维护；
- 若属于平台通用的标准化能力：应当通过规范提案将其沉淀至 @nimiplatform/sdk 的公共子路径中规范导出。

维护导入边界不是教条主义，而是确保应用长期稳定与平滑升级的基础。

出于所谓的性能考量或临时调试方便，开发者试图跳过 SDK 桥接层，直接向本地 Runtime 暴露的端口发起原始 gRPC 调用：

安全与上下文缺失：标准 SDK 客户端会自动承载桌面宿主注入的安全 Shell 会话凭据。绕过 SDK 的裸连接将被 Runtime 的安全拦截器识别为未经授权的来源，并在鉴权阶段被直接拒绝。
规范应对方式：业务必须通过 SDK 提供的标准宿主绑定客户端发起调用。若存在真实的吞吐量或流式性能瓶颈，应通过优化 SDK 传输配置或扩展标准 SDK 接口来解决，而不是脱离规范私自穿透。

边界内（属于 SDK 长期维护与承诺的稳定表面）：

边界外（属于平台各子系统的内部私有实现细节）：