XiHan.Framework.AI.Abstractions 5.0.0-preview.1

Prefix Reserved
.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher.
This is a prerelease version of XiHan.Framework.AI.Abstractions.
There is a newer prerelease version of this package available.
See the version list below for details. 
dotnet add package XiHan.Framework.AI.Abstractions --version 5.0.0-preview.1
                    


                    

                
NuGet\Install-Package XiHan.Framework.AI.Abstractions -Version 5.0.0-preview.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="XiHan.Framework.AI.Abstractions" Version="5.0.0-preview.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="XiHan.Framework.AI.Abstractions" Version="5.0.0-preview.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="XiHan.Framework.AI.Abstractions" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add XiHan.Framework.AI.Abstractions --version 5.0.0-preview.1
                    


                    

                
#r "nuget: XiHan.Framework.AI.Abstractions, 5.0.0-preview.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package XiHan.Framework.AI.Abstractions@5.0.0-preview.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=XiHan.Framework.AI.Abstractions&version=5.0.0-preview.1&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=XiHan.Framework.AI.Abstractions&version=5.0.0-preview.1&prerelease
                    


                            Install as a Cake Tool

XiHan.Framework.AI.Abstractions

AI 契约（Ring 2，RFC-0022，ADR-0017）：以 Microsoft.Extensions.AI 的 IChatClient / IEmbeddingGenerator / AITool 为线格式，框架只做目录、护栏、提示词、工具与知识库。能力 ai.chat@1、ai.embedding@1（Provider：AI.OpenAI）、ai.tools@1（本包的 AIToolsFeature 默认提供）、ai.knowledge@1（Provider：AI.VectorData）。

类型 用途
AIOptions、AIProviderOptions XiHan:AI：DefaultProvider、DefaultEmbeddingProvider、Providers:<name>（Kind 必填、Endpoint、ApiKey、ChatModel、EmbeddingModel、EmbeddingDimensions、TimeoutSeconds、Properties）、Tools:<操作 ID>、Guardrails、Knowledge、Prompts:<name>；值不合法即抛出 ArgumentException（启动失败）
IAIProviderCatalog 按名字解析 IChatClient / IEmbeddingGenerator<string, Embedding<float>>，缓存到 Invalidate；DefaultProvider / DefaultEmbeddingProvider 给出默认名（null 即没有默认；框架的 AIProviderCatalog 从配置推出）；Provider 包实现 IChatClientFactory / IEmbeddingGeneratorFactory
IAIChat、AIChatRequest 提示词渲染 → 工具绑定 → 护栏 → 解析 Provider（没写名字时取目录的 DefaultProvider）→ 调用；CompleteAsync / StreamAsync
IAIGuardrail、GuardrailVerdict、KeywordBlocklistGuardrail 输入护栏；内置关键词与提示注入护栏由 XiHan:AI:Guardrails:Enabled 开启
IAIPromptCatalog、AIPromptTemplate 提示词模板（{name} 占位符，{{ / }} 转义），显式登记优先于配置
IAIToolCatalog、OperationAIFunction、AIToolNameConvention AddAITool 的工具 + Expose.Ai 的操作桥接成 AIFunction（名 <resource>_<verb>，描述取消息目录 <操作 ID>.description），Bind(caller) 后在新作用域经完整管道执行，以调用方身份（复制主体与租户，不复制凭据）按契约授权
IKnowledgeStore ai.knowledge@1 的 Provider 契约：按集合写入 / 按文档删除 / 按块序号裁剪 / 向量搜索；重新摄入先写新块、写入成功后再裁掉多余的旧块
IKnowledgeIngestor、IKnowledgeRetriever、IRagPromptAugmenter、IChunkingStrategy 切块 → 嵌入 → 写入；问题嵌入 → 搜索 → 最低得分；检索结果拼进提示（配置的模板在启动时校验：找不到或渲染不了即启动失败，不退回内置模板；增强本身不会失败）
KnowledgeMetadataKeys 框架认识的块元数据键：title、source，提示增强依次用它们写片段的来源，都没有时用文档 ID（ADR-0116）
AIErrors、AIMessages AI_* 错误码与 ai.* 消息键（10 种区域） 
[Operation("orders.list", Expose = Expose.Http | Expose.Ai)]
public sealed class ListOrders : IOperation<ListOrdersRequest, ListOrdersResponse> { … }

var reply = await chat.CompleteAsync(new AIChatRequest
{
    Messages = [new ChatMessage(ChatRole.User, "How many orders are pending?")],
    Prompt = "assistant",
    Tools = ["orders_list"],
}, ct);

默认 Provider 名由目录给出（ADR-0110）：IAIChat 不写 Provider 时取 DefaultProvider；摄入与检索依次取请求的 Provider、XiHan:AI:Knowledge:EmbeddingProvider、DefaultEmbeddingProvider。流水线不读 XiHan:AI 的默认键，应用以自己的目录（如落库的目录）替换框架实现时默认名随目录走；两个属性同步、不做 I/O，要查库的目录持内存快照。

错误：Provider 未配置或种类无工厂、没写名字而目录没有默认（ai.provider.default_missing / ai.provider.embedding_default_missing）→ AI_NOTFOUND_001；提示词不存在 → AI_NOTFOUND_002；工具不存在 → AI_NOTFOUND_003；护栏拦截 → AI_DENIED_001；模型不可达 → AI_UNAVAILABLE_001，超时 → AI_TIMEOUT_001；没有知识库 Provider → AI_UNAVAILABLE_002；嵌入维度不一致 → AI_VALIDATION_002。

超时与取消（RFC-0022「超时与取消」，ADR-0095）：IAIChat 与知识库流水线调用 Provider 时，把它的 TimeoutSeconds 按容器的 TimeProvider 落成超时令牌、与调用方令牌链接后交给 Provider。完整应答的时限覆盖 Provider 的整次调用（含它自己的函数调用循环与其中的工具调用），嵌入是每次嵌入批调用，流式是等每个更新（含第一个）的时长、调用方处理更新的时间不算——这是已定的做法（ADR-0097）：不设整条流的总时限（会截断正常的长回答），也不退回不计时（卡住的连接没有上限），总时长由调用方的取消令牌或截止时间限制。归因只看令牌：超时令牌已触发即 AI_TIMEOUT_001（流里抛出 TimeoutException），不论调用方是否也取消、Provider 是抛出还是接住取消正常返回；只有调用方取消时抛出 OperationCanceledException，交给管道按截止令牌归因；两个都没触发时 Provider 抛出的取消视为它自己的传输超时。直接从目录解析的客户端不经这一层。

AI 配置不热更新（ADR-0074）：XiHan:AI 的全部配置——Provider、默认 Provider、提示词、护栏、工具名覆盖、知识库——在装配时读一次，改了要重启应用。框架不监听配置变化，IAIProviderCatalog.Invalidate 只丢弃缓存的客户端、用同一份选项重建；提示词目录、工具目录、护栏、知识库选项与提示增强器都在创建时取定。应用替换的目录不受此限：它自己维护 Provider 表与默认名，聊天与知识库每次调用都问它。

依赖方向

依赖 XiHan.Framework.Kernel、XiHan.Framework.Localization.Abstractions、Microsoft.Extensions.AI.Abstractions。被 AI.OpenAI、AI.VectorData、AI.Conformance、Profiles.Full 引用。

状态

P0：可用（Preview）。

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on XiHan.Framework.AI.Abstractions:

Package Downloads
XiHan.Framework.AI

曦寒框架 AI 扩展库
XiHan.Framework.AI.Conformance

曦寒框架 AI 一致性测试套件
XiHan.Framework.AI.VectorData

曦寒框架 AI 知识库的向量存储提供程序
XiHan.Framework.AI.OpenAI

曦寒框架 AI 的 OpenAI 兼容提供程序
XiHan.Framework.Profiles.Full

曦寒框架 Full 组合包

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
5.0.0-preview.2 0 11/6/2026
5.0.0-preview.1 40 11/4/2026
4.8.0 166 10/22/2026
4.7.1 111 10/21/2026
4.7.0 138 10/15/2026
4.6.2 117 10/13/2026
4.6.1 279 10/3/2026
4.6.0 146 9/25/2026
4.5.0 129 9/23/2026
4.4.0 133 9/22/2026
4.3.0 150 9/12/2026
4.2.0 178 9/4/2026
4.1.0 151 8/31/2026
4.0.0 141 8/28/2026
3.14.0 154 8/26/2026
3.13.0 174 8/15/2026
3.12.1 146 8/14/2026
3.12.0 414 8/13/2026
3.11.1 154 8/11/2026
3.11.0 381 8/11/2026
Loading failed