# NewLife.AI — 架构设计

> 版本：v3.0 | 日期：2026-04-17
> 关联文档：[需求规格说明](需求规格说明.md)

本文档采用**四层分层架构**（L1 接入 → L2 内核 → L3 能力 → L4 知识）叙述 NewLife.AI 的完整设计。

---

## 1. 系统架构总览

### 1.1 两层工程结构

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

扩展包：

- **NewLife.AI.Extensions**（net8/10）：ASP.NET Core DI 注册助手 + MCP over HTTP（SSE + HTTP Stream） + `AspNetMcpServer`

### 1.2 四层架构视图

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

### 1.3 架构扩展点

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

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

---

## 2. L1 接入交互层

### 2.1 接入方式

| 渠道 | 协议 | 入口 | 说明 |
|------|------|------|------|
| Web 前端 | HTTP + SSE | `/api/conversations/*`、`/api/messages/*` 等 20 个控制器 | 主力渠道，React 19 + TypeScript + Vite |
| API 网关 | OpenAI / Anthropic / Gemini 协议 | `/v1/chat/completions`、`/v1/messages`、`/v1/gemini/...` | 外部系统接入，AppKey 认证 |
| 办公平台回调 | 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`

**内置实现**（6 个）：

| 实现类 | 平台 | 特性 |
|--------|------|------|
| `DingTalkChannel` | 钉钉 | 群 / 私聊消息回调，支持 Markdown |
| `WeComChannel` | 企业微信 | 应用消息回调，支持文本 / 图片 |
| `FeishuChannel` | 飞书 | 消息事件回调，支持卡片消息 |
| `WebhookChannel` | 通用 HTTP | 自定义系统回调 |
| `SlackChannel` | Slack | Slack Bot 消息回调 |
| `TelegramChannel` | Telegram | Telegram Bot 消息 |

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

---

## 3. L2 对话内核层

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

### 3.1 核心组件

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

### 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 对齐）：

```csharp
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 能力扩展层

### 4.1 技能系统

**概念**：技能是一段 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`

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

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

```csharp
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` / `SearchRemoteService` | 联网搜索 |
| `ITranslateService` | `TranslateMyMemoryService` / `TranslateRemoteService` | 文本翻译 |
| `IWeatherService` | `WeatherNmcService`（中国）/ `WeatherWttrService`（全球）/ `WeatherRemoteService` | 天气查询 |
| `IWebFetchService` | `WebFetchDirectService` / `WebFetchRemoteService` | 网页抓取 |
| `IIpLocationService` | `IpLocationIpApiService` / `IpLocationPconlineService` / `IpLocationRemoteService` | IP 定位 |
| — | `NetworkToolService` | Ping / DNS 综合网络工具 |

**Remote 系列**：各接口均有 `xxxRemoteService` 实现，HTTP 代理到外部服务，便于私有化部署。

### 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 过滤器链

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

```csharp
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 规划器与多智能体

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

**MultiAgent**：`NewLife.AI/Agents/`

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

---

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

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

### 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` | NewLife.ChatAI | `Services/MemoryService.cs` | 记忆 CRUD、分类查询、按用户聚合 |
| `ConversationAnalysisService` | NewLife.ChatAI | `Services/ConversationAnalysisService.cs` | 异步分析对话，LLM 提取结构化知识 |
| `LearningHandler` | NewLife.ChatAI | `Handlers/LearningHandler.cs` | 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` — 清除所有记忆

### 5.6 高级扩展能力（本版本暂不包含）

以下能力架构已预留扩展点，当前版本未内置实现：
- Dream 离线蒸馏（`MemoryDistillationService`）
- 痛觉记忆（`NociceptionService`）
- 好奇心探索（`CuriosityService`）
- 知识图谱（`MemoryGraphService` + `MemoryEntity` + `MemoryRelation`）
- 每日简报（`DailyBriefingService`）
- 知识融合（`KnowledgeFusionService`，碎片进化为技能）
- 信任分级与知识审核（`TrustService` + `KnowledgeReview` + `KnowledgeHistory`）
- 智能体自我进化（`LessonsLearned`）
- 知识库 RAG（`KnowledgeBase` / `Document` / `Article` + `KnowledgeFilter`）
- 记忆检索增强（时间衰减 + MMR 多样性去重）

---

## 6. 功能完成状态矩阵

### 6.1 NewLife.AI 基础库

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

### 6.2 NewLife.ChatAI Web 应用

| # | 模块 | 功能 | 状态 |
|---|------|------|------|
| 1 | 会话 | 新建 / 列表 / 更新 / 删除 / 置顶 / 自动标题 | ✅ |
| 2 | 消息 | 发送（SSE） / 编辑 / 重新生成 / 停止生成 / 思考过程 | ✅ |
| 3 | 反馈 | 点赞 / 点踩 / 取消 | ✅ |
| 4 | 分享 | 创建 / 查看 / 撤销 | ✅ |
| 5 | 附件 | 上传 / 预览 | ✅ |
| 6 | 模型 | 列表 / 切换 | ✅ |
| 7 | 用户设置 | 获取 / 更新 / 导出 / 清除 | ✅ |
| 8 | 技能 | 管理 / 激活 / SkillBar / `@` 引用 | ✅ |
| 9 | 用户记忆 | 自动提取 / 手动管理 / API | ✅ |
| 10 | 推荐问题 | 欢迎页展示 / 后台配置 | ✅ |
| 11 | API 网关 | OpenAI / Anthropic / Gemini / Responses / Images / Models | ✅ |
| 12 | API 网关 | AppKey 认证 / 429 重试 / 用量记录 | ✅ |
| 13 | Function Calling | 自动多轮工具调用 + 交错思考 | ✅ |
| 14 | MCP | 客户端连接 + 工具发现 + Server 管理 API | ✅ |
| 15 | LearningHandler | OnBefore 注入记忆 / OnAfter 触发分析 | ✅ |
| 16 | 后台生成 | `BackgroundGenerationService` | ✅ |
| 17 | 用量统计 | 按用户 / AppKey 双维度 | ✅ |
| 18 | 管理后台 | 魔方（NewLife.Cube） | ✅ |

### 6.3 前端（React 19 + TypeScript + Vite + Zustand）

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

---

## 7. 扩展指南

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

### 7.1 新增 AI 服务商

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

```csharp
[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

```csharp
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]` 排序调用：

```csharp
[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 新增原生工具

```csharp
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 实现桌面/本机工具审批

```csharp
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 从源码运行

```bash
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 包嵌入

```csharp
using NewLife.ChatAI;

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

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

### 8.3 仅使用基础库

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

---

## 9. 相关文档

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

---

（完）
