架构设计.md

NewLife.AI — 架构设计

版本：v4.0 | 日期：2026-07-17 需求对应：需求文档 | 功能清单：功能清单

本文档采用四层分层架构（L1 接入 → L2 内核 → L3 能力 → L4 知识）叙述 NewLife.AI 社区版的完整设计。 模块编码：AI（AI Client SDK）、CHAT（对话系统）、TOOL（能力扩展）、EVO（知识进化基础版）、GW（API 网关）、IM（渠道集成）、AGENT（智能体框架）。

---

1. 系统架构总览

1.1 两层工程结构

职责边界：AI SDK 层定义接口（IChatClient、ToolChatClient、IChatFilter、IToolProvider、MCP 客户端核心等），ChatAI 应用层提供具体实现和深入使用。

┌───────────────────────────────────────────────────────┐
│  NewLife.ChatAI    ← ASP.NET Core Web 应用（net8/10） │
│  20 API Controllers + Gateway + 魔方后台 + React 前端 │
│  业务服务（MessageFlow / SkillService / MemoryService │
│    / UsageService / ModelService / McpClientService） │
│  Tool 实现（BuiltinToolService / GuardrailsHandler /  │
│    WidgetToolService / McpClientService 等）           │
│  实体（技能 / 用户记忆 / 推荐问题 / 内置工具 / ...）   │
└───────────────────────────────────────────────────────┘
                           ↑
                      依赖（SDK）
                           │
┌───────────────────────────────────────────────────────┐
│  NewLife.AI   ← 核心 SDK（net45 / netstandard2.1）    │
│  46 Clients / 5 Protocols / MCP 核心 / Agents /       │
│  Planner / IChatFilter 接口 / ToolChatClient 引擎     │
│  / IChatHandler / Memory / Channels                   │
└───────────────────────────────────────────────────────┘

扩展包：

• NewLife.AI.Extensions（net8/10）：ASP.NET Core DI 注册助手 + MCP over HTTP（SSE + HTTP Stream） + AspNetMcpServer（MCP 服务端实现，属 TOOL 层）

1.2 四层架构视图

┌──────────────────────────────────────────────────────────┐
│  L1 接入交互层                                             │
│    Web 前端(React) / API 网关(OpenAI/Anthropic/Gemini)   │
│    / 办公平台(钉钉/企微/飞书/Webhook/Slack/Telegram)      │
├──────────────────────────────────────────────────────────┤
│  L2 对话内核层                                             │
│    ChatApplicationService / MessageFlow 五阶段            │
│    / IChatHandler 链 / GatewayService / BackgroundGeneration │
│    / MessageRateLimiter / SSE 流式协议                    │
├──────────────────────────────────────────────────────────┤
│  L3 能力扩展层                                             │
│    技能(TOOL) / 原生工具实现(TOOL) / MCP 实现(TOOL)      │
│    / Filter 实现(TOOL) / IChatHandler(TOOL)              │
│    / Planner(AGENT) / 多智能体(AGENT)                    │
├──────────────────────────────────────────────────────────┤
│  L4 知识进化层（基础版）                                    │
│    用户记忆 10 类(EVO) / ConversationAnalysisService     │
│    / 推荐问题(EVO) / LearningHandler 自动注入(EVO)       │
├──────────────────────────────────────────────────────────┤
│  L5 基础设施（无独立文档）                                  │
│    NewLife.AI SDK(AI) / XCode / Cube                     │
└──────────────────────────────────────────────────────────┘

⚠️ 社区版不包含 KNOW（知识库 RAG）、PROJ（项目运营）、DESK（桌面客户端）模块及 TOOL/GW/EVO/IM 各模块的高级子功能。完整功能范围见需求文档和功能清单。

1.3 架构扩展点

核心架构预留了完整的二次开发扩展点：

扩展点	接口 / 基类	说明
处理器扩展	IChatHandler / ChatHandlerBase	三段式 OnBefore/Interceptor/OnAfter，通过 [ChatHandlerOrder] 控制顺序
工具提供者	IToolProvider	自定义工具来源（数据库 / 远程调用 / 复杂策略）
聊天过滤器	IChatFilter（接口在 AI SDK，实现见 TOOL-4）	洋葱圈模型，在对话前后插入自定义逻辑；具体 Filter 实现（Guardrails/安全护栏/记忆注入等）在 TOOL 应用层
记忆进化	MemoryService	可继承扩展知识蒸馏、知识图谱等高级进化能力
工具审批	IToolApprovalProvider	工具执行前拦截，可实现弹窗 / 日志 / 权限控制

---

2. L1 接入交互层

2.1 接入方式

渠道	协议	入口	说明
Web 前端（CHAT）	HTTP + SSE	/api/conversations/*、/api/messages/* 等控制器	主力渠道，React 19 + TypeScript + Vite
API 网关（GW）	OpenAI / Anthropic / Gemini 协议	/v1/chat/completions、/v1/messages、/v1/gemini/...	外部系统接入，AppKey 认证
办公平台回调（IM）	HTTP 回调	/api/channel/{code}/callback	钉钉 / 企微 / 飞书 / Webhook
URL 参数跳转	浏览器跳转（纯前端）	/chat?prompt=xxx	业务系统跳转，自动填充并发送；支持 autoSend=0 仅填充不发送

桌面客户端不包含于本版本，可通过 IToolApprovalProvider 接口自行实现。

2.2 Web 前端

技术栈：React 19 + TypeScript + Vite + Zustand（状态管理）

主要页面：

• / — 欢迎页（WelcomePage），展示推荐问题
• /chat — 新建对话临时会话
• /chat/:id — 会话对话页
• /share/:token — 共享只读页

核心组件目录：Web/src/components/

• atoms/ — 原子组件（Button / Icon / Modal 等）
• chat/ — 对话组件（MessageBubble / ThinkingBlock / ToolCallBadge 等）
• input/ — 输入组件（ChatInput / AttachmentChip / SkillBar）
• settings/ — 设置组件（各设置 Tab 页）
• sidebar/ — 侧边栏

状态管理（Zustand）：chatStore（会话列表 / 活跃会话 / 消息流） + settingsStore（持久化设置） + uiStore + toastStore

2.2.1 URL 参数跳转直发

业务系统可通过浏览器跳转携带参数，自动填充输入框并发送；传 autoSend=0 时仅填充不发送，由用户手动修改后发送：

/chat?prompt=xxx&model=deepseek-r1&thinking=think&skill=coder
/chat?prompt=xxx&autoSend=0

参数	说明	默认值
prompt	要发送的消息（≤ 6000 字，必填）	—
model	模型 code 或 name	用户默认模型
thinking	fast|auto|think	用户当前设置
skill	技能 code	无
sidebar	0=折叠（默认）|1=展开	0
autoSend	1=延迟 500ms 自动发送（默认）；0=仅填充输入框	1

流程：mount 阶段预填充 + 折叠侧边栏 + 清理 URL → appReady 后应用模型/思考模式 → autoSend=true 时延迟 500ms 自动发送。URL 清理（navigate replace）防止刷新重发。

2.3 API 网关

入口：GatewayController，按协议分发到 GatewayService；认证通过 Authorization: Bearer sk-xxxx。

支持协议：

协议	路由	说明
OpenAI ChatCompletions	POST /v1/chat/completions	流式 / 非流式 / 函数调用 / 视觉
OpenAI Responses	POST /v1/responses	推理模型（o3 / gpt-5 等）
Anthropic Messages	POST /v1/messages	Claude 系列
Google Gemini	POST /v1/gemini/...	Gemini 系列
图像生成	POST /v1/images/generations	OpenAI 图像协议
图像编辑	POST /v1/images/edits	multipart/form-data
模型发现	GET /v1/models	可用模型列表

关键特性：

• 多协议入站 → 统一内部 ChatRequest / ChatResponse → 出站适配回原协议
• 上游 429 指数退避重试（带随机抖动，最多 5 次）
• 每次调用记录 Token 消耗、耗时到数据库，归属用户 + AppKey 双维度
• 全功能对等：走 ChatPipeline，享受记忆注入与技能增强

2.4 办公平台渠道

抽象：NewLife.AI/Channels/IMessageChannel

内置实现（11 个）：

实现类	平台	特性
DingTalkChannel	钉钉	群 / 私聊消息回调，支持 Markdown
WeComChannel	企业微信	应用消息回调，支持文本 / 图片
FeishuChannel	飞书	消息事件回调，支持卡片消息
WeComBotChannel	企微智能机器人	Webhook 群聊高频
WeChatMpChannel	公众号（微信 MP）	订阅号/服务号接入
WeChatKfChannel	微信客服（微信 KF）	客服系统接入
QQChannel	QQ 机器人	QQ 官方开放平台
WebhookChannel	通用 HTTP	自定义系统回调
SlackChannel	Slack	Slack Bot 消息回调
TelegramChannel	Telegram	Telegram Bot 消息
DiscordChannel	Discord	Gateway 长连接

每个渠道独立校验签名 / Token。回调入口统一为 POST /api/channel/{code}/callback。

---

3. L2 对话内核层（CHAT / GW）

对话内核层是系统中枢，负责会话管理、消息处理、状态持久化和后台生成。

3.1 核心组件

组件	模块	所在工程	职责
ChatApplicationService	CHAT	NewLife.ChatAI	核心业务入口，编排全链路
MessageService	CHAT	NewLife.ChatAI	消息实体 CRUD 与查询
GatewayService	GW	NewLife.ChatAI	网关协议适配，AiClientRegistry 路由
ConversationAnalysisService	EVO	NewLife.ChatAI	对话异步分析 + 知识提取
MessageFlow	CHAT	NewLife.ChatAI	五阶段模板：Validate→Prepare→Execute→Persist→PostProcess
IChatHandler	TOOL	NewLife.AI	处理器接口，三段式 OnBefore/InvokeAsync/OnAfter
ChatHandlerChain	TOOL	NewLife.AI	管理并排序 BeforeHandlers/AfterHandlers/Interceptors
BackgroundGenerationService	CHAT	NewLife.AI	后台继续生成任务管理
MessageRateLimiter	CHAT	NewLife.AI	消息速率限制
UsageService	GW	NewLife.ChatAI	用量记录与统计查询

3.2 IChatHandler 处理器链

IChatHandler（NewLife.AI/Handlers/）三段式架构，按 [ChatHandlerOrder] 排序：

ChatHandlerChain
  ├─ BeforeHandlers (OnBefore)
  │    └─ LearningHandler.OnBefore — 从 MemoryService 获取记忆注入 System Prompt
  │    └─ ... 自定义 Before Handler
  ├─ Interceptors (InvokeAsync)
  │    └─ FilteredChatClient（IChatFilter 洋葱圈）
  │         └─ ToolChatClient（自动工具调用循环）
  │              └─ RawClient（AiClientRegistry 创建的原始客户端）
  └─ AfterHandlers (OnAfter)
       └─ LearningHandler.OnAfter — fire-and-forget 触发 ConversationAnalysisService
       └─ ... 自定义 After Handler

可通过继承 ChatHandlerBase 或实现 IChatHandler 叠加自定义逻辑，通过 [ChatHandlerOrder(N)] 控制执行顺序。

3.3 MessageFlow 五阶段模板方法

┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐
│ Validate │→│ Prepare  │→│ Execute  │→│ Persist  │→│ PostProcess│
│ 参数校验   │  │ 上下文准备 │  │ 调用管道   │  │ 写库       │  │ 过滤器后置  │
└──────────┘  └──────────┘  └──────────┘  └──────────┘  └────────────┘

阶段	说明
Validate	参数合法性、用户权限、模型可用性、AppKey 配额、会话所有权校验
Prepare	装配初始消息列表（System Prompt + 历史 + 当前用户消息），调用 IChatHandler.OnBefore 链（如 LearningHandler 注入用户记忆）
Execute	调用 IChatHandler 链 Execute 阶段获取模型回答，处理 SSE、思考内容、工具调用
Persist	保存用户消息 / AI 回答 / 工具调用记录 / 用量记录，使用事务保证一致性
PostProcess	Fire-and-forget 执行 OnStreamCompletedAsync：学习提取、推荐追问生成

3.4 轻量直连调用流程

适用于直接使用 NewLife.AI 基础库、不经过 Web 应用的轻量场景。

核心接口（MEAI 对齐）：

interface IChatClient : IDisposable
{
    Task<ChatResponse> GetResponseAsync(ChatRequest request, CancellationToken ct);
    IAsyncEnumerable<ChatResponse> GetStreamingResponseAsync(ChatRequest request, CancellationToken ct);
}

扩展方法（ChatClientExtensions）：

• AskAsync(String prompt) — 单轮文本问答
• AskAsync((role, content)[] messages) — 多角色消息
• GetStreamingResponseAsync(IList<ChatMessage>, ChatOptions) — 流式

创建方式：

1. 直接 new：new DashScopeChatClient("api-key", "qwen-plus")
2. 注册表创建：AiClientRegistry.Default.CreateClient("DashScope", "api-key", "qwen-plus")
3. 链式管道：new ChatClientBuilder().UseDashScope(...).UseFilters(...).UseTools(...).Build()
4. ASP.NET DI：services.AddDashScope("api-key", "qwen-plus")

3.6 完整消息处理时序（Web 链路）

前端 SSE
  ↓
MessagesController.Send
  ↓
ChatApplicationService.StreamMessageAsync
  ↓ (执行 MessageFlow 五阶段)
  ├─ Validate：参数校验
  ├─ Prepare：调用 LearningHandler.OnBefore 注入用户记忆
  ├─ Execute：IChatHandler 链（FilteredChatClient → ToolChatClient → RawClient）
  │              └─ RawClient（OpenAI/Anthropic/... 原始客户端）
  ├─ Persist：写入会话/消息/用量
  └─ PostProcess：fire-and-forget 触发 LearningHandler.OnAfter 自学习分析
  ↓
SSE message_done → 前端

3.7 后台继续生成

BackgroundGenerationService（位于 NewLife.AI/Services/）：用户切换页面后对话继续生成，回来时前端重新加载消息可查询到完整结果。

---

4. L3 能力扩展层（TOOL / AGENT）

L3 层包含两个模块：TOOL（技能/工具/MCP/过滤器/处理器）和 AGENT（Planner/多智能体/反思/HITL）。

4.1 TOOL — 技能系统

概念：技能是一段 Markdown 格式的结构化提示文本，注入 System Prompt。

实体（NewLife.ChatAI/Entity/系统配置/技能.cs）：

• Code 唯一编码、Name 名称、Content 提示内容、Category 分类、Triggers 触发词、Enable 启用开关、IsSystem 系统内置标记

服务：NewLife.ChatAI/Services/SkillService.cs

• GetSkillBarList(userId, maxCount=8) — SkillBar 数据（最近使用 3 + 系统技能补充）
• MatchSkillByContent() — 触发词自动匹配
• RecordUsage() — 最近使用写入 Parameter 参数表

@ 递归引用规则：最大深度 3 层；ABA 循环自动中断；引用不存在保留原文不报错。

系统内置技能：general / coder / writer / translator / analyst / researcher 六个

API：SkillApiController

• GET /api/skills — 列表
• POST /api/skills — 创建
• PUT /api/skills/{id} — 更新
• DELETE /api/skills/{id} — 删除
• GET /api/skills/bar — SkillBar 数据

4.2 原生 .NET 工具

工具提供者统一接口：NewLife.AI/Tools/IToolProvider.cs

interface IToolProvider
{
    IList<ChatTool> GetTools();
    Task<String> CallToolAsync(String toolName, String argumentsJson, CancellationToken ct);
}

注册流程（反射 + XML 注释）：

public class WeatherService
{
    /// <summary>获取指定城市的实时天气信息</summary>
    [ToolDescription("get_weather")]
    public async Task<String> GetWeatherAsync(
        [Description("城市名称")] String city) { ... }
}

var registry = new ToolRegistry();
registry.AddTools<WeatherService>(instance);        // [ToolDescription] 扫描
registry.AddToolsFromAssembly(assembly);            // 程序集批量扫描
registry.AddTool("name", handler, "描述");          // 委托注册

核心组件（NewLife.AI/Tools/）：

组件	职责
ToolDescriptionAttribute	标注工具方法
ToolSchemaBuilder	反射 + XML 注释 → JSON Schema
ToolRegistry : IToolProvider	工具注册表
ToolChatClient : DelegatingChatClient	装饰器，自动循环工具调用直到文本响应
BuiltinToolService	内置工具集合聚合
IToolApprovalProvider	工具执行前审批拦截接口

ChatAI 提供的工具提供者：

• DbToolProvider — 按数据库 内置工具 实体的 Enable 开关动态路由
• HolidayToolService — 节假日 / 节气查询
• CurrentUserTool — 当前用户档案

4.3 内置工具服务

NewLife.AI/Tools/ 提供开箱即用的工具服务：

接口	实现	工具
ISearchService	SearchBingService / SearchDuckDuckGoService / SearchSerperService	联网搜索
ITranslateService	TranslateMyMemoryService	文本翻译
IWeatherService	WeatherNmcService（中国）/ WeatherWttrService（全球）	天气查询
IWebFetchService	WebFetchDirectService	网页抓取
IIpLocationService	IpLocationPconlineService	IP 定位
—	NetworkToolService	Ping / DNS 综合网络工具

4.4 MCP 工具

NewLife.ChatAI                 外部 MCP Server
  McpClientService  ──stdio/HTTP SSE──▶  MCP 工具服务器
  AspNetMcpServer   ◀──HTTP SSE────       外部 MCP 客户端

客户端（NewLife.ChatAI/Services/McpClientService.cs）：

• DiscoverToolsAsync(serverId) — 工具发现
• CallToolAsync(toolName, arguments) — 工具调用
• GetAllToolsAsync() — 汇总所有启用 Server 的工具；冲突时自动加前缀

服务端（NewLife.AI.Extensions.AspNetMcpServer）：将本系统 IToolProvider 暴露为标准 MCP 服务

API（McpApiController）：

• GET /api/mcp/servers / POST / PUT / DELETE
• POST /api/mcp/servers/{id}/discover — 手动触发发现
• GET /api/mcp/servers/{id}/tools — 查看工具列表

Server 类型：stdio（本机进程）/ sse（HTTP 长连接）/ http

4.5 TOOL — 过滤器链

IChatFilter（NewLife.AI/Filters/）：洋葱圈模型

interface IChatFilter
{
    Task OnChatAsync(ChatFilterContext ctx,
        Func<ChatFilterContext, CancellationToken, Task> next,
        CancellationToken ct);
    Task OnStreamCompletedAsync(ChatFilterContext ctx, CancellationToken ct);
}

内置处理器：LearningHandler（NewLife.ChatAI/Handlers/LearningHandler.cs，实现 IChatHandler）

• OnBefore：从 MemoryService 获取相关记忆并注入 System Prompt
• OnAfter：触发 ConversationAnalysisService 异步分析对话，提取知识

4.6 AGENT — 规划器与多智能体

Planner：NewLife.AI/Planner/FunctionCallingPlanner — 将自然语言目标分解为多步工具调用计划并执行

MultiAgent：NewLife.AI/Agents/

类	说明
IAgent	智能体统一接口
ConversableAgent	可与工具交互的单智能体
GroupChat	多智能体群聊（RoundRobin 或 LLM Selector）
ParallelGroupChat	并行执行多智能体
DelegatingAgent	智能体委派装饰器
AgentAsTool	将智能体封装为工具
AgentMessage	协作消息模型

4.5 可视化与交互工具

NewLife.ChatAI/Tools/ 提供三类可视化与交互工具，均注册为 [ToolDescription] 原生工具：

类型	工具	服务	说明
Widget	show_widget	WidgetToolService	SVG/HTML 直接渲染到对话气泡，前端 sandbox iframe 隔离
图表	show_chart	ChartToolService	ECharts 交互式图表，JSON 规范输出
图表	show_timeline	TimelineToolService	时序事件时间线可视化
图表	show_kanban	KanbanToolService	看板卡片布局
图表	show_mindmap	MindmapToolService	思维导图树结构渲染
图表	show_china_map	MapAnnotationToolService	中国区域热力/标注地图（返回格式兼容 show_widget）
文档	build_ppt	BuildPptToolService	PowerPoint 演示文稿生成，支持 italic/underline 文字样式，widgetSrc 模式嵌入 show_widget 卡片
文档	build_excel	BuildExcelToolService	Excel 电子表格生成，支持列宽/数字格式/条件格式（数据条/色阶/阈值）
文档	build_doc	BuildDocToolService	Word 文档生成，支持 divider/callout/kpi/quote/code 等 11 种元素类型 + 段落文本格式 + 表格样式
交互	ask_user	CodingTools.AskUserAsync	向用户提问并获取回答（控制台环境）；ToolChatClient 内置同轮豁免（同名同参去重跳过 ask_user）

卡片风格关联：CardStyleHandler（位于 NewLife.ChatAI/Handlers/，Before=105）在 OnBefore 阶段检测当前对话是否使用了 show_* / build_* 系列工具，若命中则将 CardStyleService 生成的风格提示词注入 System Prompt，指导 AI 生成符合特定视觉规范的内容。风格生效顺序：会话级 > 用户级 > 系统默认。

人类决策检查点流程（StarChat 商用版 RequestDecisionToolService 完整实现）：

AI 不确定方向
  → 调用 ask_user(questions, timeoutSeconds)
  → 前端渲染多组 Tab 选项卡片
  → 用户全部作答 → POST /api/checkpoint/{id}/respond
  → CheckpointService 解除阻塞
  → 工具返回各组用户选择结果
  → AI 依据选择继续推理

---

5. L4 知识进化层 — EVO（基础版）

NewLife.AI 社区版提供基础级知识进化能力，让 AI 自动从对话中提取结构化用户记忆。

⚠️ 高级进化能力（痛觉记忆、好奇心探索、蒸馏/融合、知识图谱、知识库 RAG 等）属 StarChat 商用版范围，社区版不包含。

5.1 10 类用户记忆分类

对标 Mem0 / ChatGPT Memory / Claude Projects：

分类	说明
身份信息	姓名 / 年龄 / 性别 / 地域等
偏好	沟通风格 / 内容偏好
习惯	常用工具 / 工作节奏
兴趣	爱好 / 关注领域
背景	教育 / 从业经历
职业	当前职业 / 岗位职责
目标	近期 / 长期目标
人际关系	家人 / 同事 / 重要关系人
技能专长	技术栈 / 专业领域
交互指令	用户显式指令（如"以后用简体中文回答"）

实体：NewLife.ChatAI/Entity/知识进化/用户记忆.cs（UserMemory）

5.2 记忆生命周期

对话流结束
  ↓
LearningHandler.OnAfter
  ↓ fire-and-forget
ConversationAnalysisService.AnalyzeAsync
  ↓ (调用 LLM 结构化提取)
MemoryService.AddOrUpdateAsync
  ↓
数据库持久化（UserMemory 表）
  ↓
下次对话前 LearningHandler.OnBefore 注入 System Prompt

5.3 关键服务

服务	模块	所在工程	职责
MemoryService	EVO	NewLife.ChatAI	记忆 CRUD、分类查询、按用户聚合
ConversationAnalysisService	EVO	NewLife.ChatAI	异步分析对话，LLM 提取结构化知识
LearningHandler	EVO	NewLife.ChatAI	IChatHandler：OnBefore 注入记忆 / OnAfter 触发学习

5.4 推荐问题

实体：NewLife.ChatAI/Entity/系统配置/推荐问题.cs

• 管理员在后台配置引导性推荐问题
• 前端欢迎页（WelcomePage）展示，点击即作为用户消息发送

5.5 记忆管理 API

MemoryApiController：

• GET /api/memory — 记忆列表（支持分类筛选）
• POST /api/memory — 手动添加记忆
• PUT /api/memory/{id} — 更新
• DELETE /api/memory/{id} — 删除
• DELETE /api/memory — 清除所有记忆

---

6. 功能完成状态矩阵

完整功能清单详见功能清单.md，此处仅列出各模块关键组件状态。

6.1 AI — NewLife.AI 基础库

编码	模块	功能	状态
AI-1	AI	核心协议	IChatClient 接口
AI-2	AI	AiClientRegistry（反射扫描 [AiClient]）	✅
AI-3	AI	AiClientAttribute / AiClientModelAttribute	✅
AI-4	AI	ChatClientBuilder 中间件管道	✅
AI-5	AI	DelegatingChatClient 装饰器基类	✅
AI-6	AI	OpenAIChatClient + BuiltinChatClient（37 OpenAI 兼容）	✅
AI-7	AI	DeepSeekChatClient	✅
AI-8	AI	AnthropicChatClient	✅
AI-9	AI	GeminiChatClient	✅
AI-10	AI	OllamaChatClient	✅
AI-11	AI	DashScopeChatClient	✅
AI-12	AI	AzureAIChatClient（部署名称 URL + api-key）	✅
AI-13	AI	BedrockChatClient（AWS SigV4）	✅
AI-14	AI	NewLifeAIChatClient（级联转发）	✅
AI-15	AI	IChatFilter + FilteredChatClient	✅
AI-16	TOOL	ToolDescriptionAttribute + ToolSchemaBuilder	✅
AI-17	TOOL	ToolRegistry + ToolChatClient 多轮循环	✅
AI-18	TOOL	内置工具（搜索 / 天气 / 翻译 / IP / WebFetch / 网络诊断）	✅
AI-19	TOOL	IToolApprovalProvider 审批接口	✅
AI-20	AGENT	ConversableAgent / GroupChat / ParallelGroupChat	✅
AI-21	AGENT	DelegatingAgent / AgentAsTool	✅
AI-22	AGENT	FunctionCallingPlanner	✅
AI-23	AI	ISemanticMemory + IVectorStore（接口 + 内存实现）	✅
AI-24	TOOL	MCP Server + 客户端 + McpToolManager	✅
AI-25	IM	IMessageChannel + 11 渠道（钉钉/企微/企微机器人/飞书/公众号/微信客服/QQ/Slack/Telegram/Discord/Webhook）	✅
AI-26	CHAT	BackgroundGenerationService + MessageRateLimiter	✅
AI-27	AI	AspNetMcpServer（NewLife.AI.Extensions）	✅
AI-28	AI	AddOpenAI / AddDashScope / AddAnthropic 等 DI 专属注册 + Keyed 变体	✅

6.2 CHAT/GW/EVO — NewLife.ChatAI Web 应用

模块	功能	状态	说明
CHAT	会话：新建/列表/更新/删除/置顶/自动标题	✅
CHAT	消息：发送(SSE)/编辑/重新生成/停止生成/思考过程	✅
CHAT	反馈：点赞/点踩/取消	✅
CHAT	分享：创建/查看/撤销	✅
CHAT	附件：上传/预览（图片+文档）	✅
CHAT	模型：列表/切换/思考模式	✅
CHAT	用户设置：获取/更新/导出/清除	✅
TOOL	技能：管理/激活/SkillBar/@引用	✅
TOOL	工具：注册/审批/内置工具（搜索/天气/翻译/IP/网络等）	✅
TOOL	工具增强：ToolCallContext/结构化错误返回/熔断/渐进式发现	✅
TOOL	MCP：客户端连接+工具发现+Server管理API	✅
TOOL	数据库工具：search_table + run_sql	✅
TOOL	可视化Widget：show_widget/图表/文档生成	✅
EVO	用户记忆：自动提取/手动管理/API/推荐问题	✅
EVO	LearningHandler：OnBefore注入记忆/OnAfter触发分析	✅
GW	API 网关：多协议/AppKey/429重试/用量记录	✅
CHAT	后台生成：BackgroundGenerationService	✅
GW	用量统计：按用户/AppKey 双维度	✅
IM	11 渠道：钉钉/企微/飞书/公众号/微信客服/QQ/Slack/Telegram/Discord/Webhook等	✅
CHAT	管理后台：魔方（NewLife.Cube）	✅

6.3 CHAT — 前端（React 19 + TypeScript + Vite + Zustand）

模块	功能	状态
CHAT	布局：左右分栏 + 响应式（768px 断点）	✅
CHAT	侧边栏：新建对话/分组列表/搜索/置顶/滚动加载	✅
CHAT	输入区：多行自动伸缩+附件+思考模式+SkillBar	✅
CHAT	对话区：SSE流式+Markdown+KaTeX+Mermaid+代码高亮	✅
CHAT	对话区：思考过程折叠+工具调用块+交错思考	✅
CHAT	对话区：图像Lightbox+多模态输入	✅
CHAT	设置：通用/对话/数据/AppKey/用量/技能/记忆/MCP	✅
CHAT	分享：创建链接/只读浏览	✅
CHAT	会话：自动标题/重命名/删除/置顶/编辑消息	✅

---

7. 扩展指南

面向二次开发者，以下是常见扩展场景：

7.1 新增 AI 服务商

继承 AiClientBase 或 OpenAIChatClient，添加 [AiClient] 特性：

[AiClient("MyAI", "我的服务", "https://api.myai.com/v1",
    Description = "自定义 AI 服务")]
[AiClientModel("myai-latest", "MyAI Latest",
    Code = "MyAI", FunctionCalling = true, Vision = true)]
public class MyAiChatClient : OpenAIChatClient
{
    public MyAiChatClient() { }
    public MyAiChatClient(String apiKey, String? model = null, String? endpoint = null)
        : base(apiKey, model, endpoint) { }
}

AiClientRegistry 启动时自动发现，无需手动注册。

7.2 新增 IChatFilter

public class ContentAuditFilter : IChatFilter
{
    public async Task OnChatAsync(ChatFilterContext ctx,
        Func<ChatFilterContext, CancellationToken, Task> next,
        CancellationToken ct)
    {
        // before：敏感词过滤（可修改 ctx.Request）
        await next(ctx, ct);
        // after：读取 ctx.Response，写审计日志
    }

    public async Task OnStreamCompletedAsync(ChatFilterContext ctx, CancellationToken ct)
    {
        // 流式结束回调
    }
}

通过 ChatClientBuilder.UseFilters(new ContentAuditFilter()) 或 DI 注册使用。

7.3 新增 IChatHandler

实现 IChatHandler（或继承 ChatHandlerBase）并通过 DI 注册，MessageFlow 会自动按 [ChatHandlerOrder] 排序调用：

[ChatHandlerOrder(150)]
public class MyHandler : ChatHandlerBase
{
    public override Task OnBefore(IChatContext context, CancellationToken cancellationToken)
    {
        // 在调用 LLM 前修改上下文消息
        context.ContextMessages.Insert(0,
            new ChatMessage { Role = "system", Content = $"当前时间：{DateTime.Now:yyyy-MM-dd HH:mm}" });
        return Task.CompletedTask;
    }

    public override Task OnAfter(IChatContext context, CancellationToken cancellationToken)
    {
        // 在 LLM 返回后异步处理
        return Task.CompletedTask;
    }
}

// DI 注册
services.AddSingleton<IChatHandler, MyHandler>();

7.4 新增原生工具

public class MyTools
{
    /// <summary>查询当前时间</summary>
    [ToolDescription("get_current_time")]
    public String GetCurrentTime() => DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss");
}

// 注册
var registry = new ToolRegistry();
registry.AddTools<MyTools>(new MyTools());

// DI 场景
services.AddSingleton<IToolProvider>(_ =>
{
    var r = new ToolRegistry();
    r.AddTools<MyTools>(new MyTools());
    return r;
});

7.5 实现桌面/本机工具审批

public class MyApprovalProvider : IToolApprovalProvider
{
    public async Task<ToolApprovalResult> RequestApprovalAsync(
        String toolName, String? argumentsJson, CancellationToken ct)
    {
        // 弹出确认 UI，返回结果
        return new ToolApprovalResult { Approved = true };
    }
}

// 挂入管道
var client = rawClient.AsBuilder()
    .UseTools(new MyApprovalProvider(), toolProviders)
    .Build();

可通过 IToolApprovalProvider 接口实现工具执行前审批拦截。

---

8. 部署

8.1 从源码运行

git clone https://github.com/NewLifeX/NewLife.AI.git
cd NewLife.AI
cd Web && pnpm install && pnpm build && cd ..
cd NewLife.ChatAI
dotnet run --framework net8.0

浏览器访问 http://localhost:5000。默认使用 SQLite，开箱即用；首次启动通过魔方后台 /Admin 配置服务商与模型。

8.2 NuGet 包嵌入

using NewLife.ChatAI;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddChatAI();

var app = builder.Build();
app.UseChatAI(redirectToChat: true);
app.Run();

8.3 仅使用基础库

using var client = new DashScopeChatClient("api-key", "qwen-plus");
var reply = await client.AskAsync("你好");

---

9. 相关文档

• 需求规格说明 — 功能目标、非功能需求、边界约束
• AI 编排框架需求
• API 网关需求
• MCP 架构
• 技能管理需求
• 自学习系统需求
• 对话数据保存流程
• 功能模块清单

---

（完）