架构
这套架构将公共契约、提供方选择和厂商专属传输代码分开。
这条边界有意比任何一家厂商的 API 更精简：它只包含使用方可跨提供方依赖的操作；请求选项元数据则允许提供方包公开有价值的差异，而不必把这些差异强加给每个使用方。
| 层级 | 职责 |
|---|---|
| 核心层 | 定义能力接口及与提供方无关的错误 |
| 注册层 | 接收提供方注册并选择活动服务 |
| 提供方插件 | 解析厂商配置并执行 API 请求 |
| 使用方插件 | 使用所选服务，不依赖具体厂商 |
提供方生命周期
提供方插件通过 ctx.aiProviders 注册 AiProvider。提供方包含稳定 ID、显示名称、可选设置元数据，以及其支持能力的工厂函数。注册受 Cordis 作用域管理，因此卸载插件会同时移除提供方。
运行时为所选提供方公开以下服务门面：
| 上下文服务 | 能力 |
|---|---|
ctx.embeddings | 文本嵌入 |
ctx.rerankers | 重排 |
ctx.textToSpeech | 文本转语音 |
ctx.apiSpeechToText | 文件转录 |
ctx.streamingSpeechToText | 实时转录（提供方支持时） |
ctx.imageGeneration | 图像生成 |
ctx.decisions | 决策 |
门面在每次调用时解析当前提供方，因此配置变更无需重建依赖插件即可生效。
一次调用如何穿过系统
- 使用方从 Cordis 上下文调用能力服务。
- 运行时读取当前提供方选择，并通过该提供方的工厂取得服务。
- 并发门控根据能力、路由和优先级放行调用。
- 厂商服务解析当前连接和凭据引用，然后执行请求。
- 实现验证响应并返回与提供方无关的结果，或抛出
AiError。
凭据始终保存在 DSH 的凭据服务中。配置档案只保存引用，因此使用方插件和这些提供方包都无需在自身配置里持久化密钥值。
语言模型路由
语言模型以 DSH 模型路由注册，而不是作为只能选择一个的服务，因此多个已配置路由可以共存。提供方还可向 UI 描述带本地化标签和默认值的请求选项。
错误模型
提供方错误会统一为 AiError，并带有六种稳定错误码之一：not-configured、unavailable、rejected、invalid-input、unsupported 或 cancelled。使用方无需解析厂商错误文本即可处理失败；消息和保留的原始原因只用于诊断，不属于兼容性契约。
兼容性边界
核心包是使用方与第三方提供方的依赖边界。运行时和本项目维护的提供方包可以在其后演进，但修改核心方法、结果结构、错误码或服务名称会影响每一个实现和使用方。厂商专属控制项应留在提供方请求选项元数据中，除非它能在不同实现之间得到一致定义。