用途：帮助 AI 编码助手正确查询、解释、集成和调试 Halo AI Foundation 的 Java SDK、浏览器/Vue SDK、UI Message 后端到前端传输，以及 FormKit 的 aiModelSelector。核心原则是把它当作独立 SDK，所有公开类型、方法、选项、事件和包导出都必须对照目标项目所用版本的文档与源码验证，不得凭记忆或从其他同名 AI 库翻译 API。
证据顺序：优先使用工作区中已存在的 AI Foundation 源码检出（含 api/、dev/、ui/packages/sdk/）；否则检查目标项目的依赖版本，Java 为 run.halo.aifoundation:api:<version>，浏览器/Vue 为 @halo-dev/ai-foundation-sdk，并读取 Gradle 模块缓存中的源码 JAR 或 node_modules 中的声明与运行时文件。仅在依赖未安装、已安装产物无法回答或需要指南与实现细节时，才克隆官方仓库到 .reference/plugin-ai-foundation，并刷新标签后按 v<version> 或 origin/main 检出。
集成默认做法：Java API 以 compileOnly 引入，在 spec.pluginDependencies 声明 ai-foundation，跨 ApplicationContext 使用 ExtensionGetter.getEnabledExtension(AiModelService.class)，以 AiModel.metadata.name 作为 modelName，通过 AiModelService 解析 LanguageModel、EmbeddingModel、RerankingModel 或 ImageGenerationModel；设置中使用 aiModelSelector 而非导入 Console 内部组件。业务关注点（授权、限流、持久化、分块、向量存储、附件生命周期、错误提示）保留在使用方插件。
运行时契约：保持 Reactor 非阻塞，不在请求路径调用 block()；prompt 与 messages 二选一，可与 system 组合；保留 responseMessages 以支持工具循环；按需消费 StreamTextResult 的各类投影；工具调用与结果或错误一一配对；通过 Java UI Message API 校验转换后再执行模型；经 UIMessageStreamResponse 发送流头与 [DONE]；持久化最终归约后的 UI 消息。
验证：按改动面运行 ./gradlew compileJava、./gradlew test、./gradlew :api:compileJava，或 cd ui 后 pnpm --filter @halo-dev/ai-foundation-sdk typecheck 与 test。报告时说明所用 SDK 版本或仓库 ref、公开类型与文档文件、已验证行为与使用方策略的区别，以及实际运行的检查。限制：资料未提供具体版本号、价格或平台支持范围，需以目标项目实际依赖为准。