@ibiz-template-plugin/ai-chat 0.0.82 → 0.0.84
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.es.js +3069 -2778
- package/dist/index.legacy.js +1 -1
- package/dist/style.css +1 -1
- package/dist/types/components/flat-chat-container/flat-chat-container.d.ts +67 -0
- package/dist/types/components/index.d.ts +1 -0
- package/dist/types/controller/ai-topic/ai-topic.controller.d.ts +3 -4
- package/dist/types/controller/chat/chat-base.controller.d.ts +151 -0
- package/dist/types/controller/chat/flat-chat.controller.d.ts +78 -0
- package/dist/types/controller/chat/modal-chat.controller.d.ts +77 -0
- package/dist/types/controller/index.d.ts +2 -1
- package/dist/types/index.d.ts +2 -2
- package/dist/types/interface/i-chat-container/i-chat-container.d.ts +6 -0
- package/dist/types/interface/i-chat-controller/i-chat-controller.d.ts +30 -0
- package/dist/types/interface/index.d.ts +1 -0
- package/docs/ARCHITECTURE.md +399 -0
- package/package.json +2 -1
- package/dist/types/controller/chat/chat.controller.d.ts +0 -131
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { IContainerOptions } from '../../interface';
|
|
2
|
+
import { AiChatController } from '../ai-chat/ai-chat.controller';
|
|
3
|
+
import { ChatBaseController } from './chat-base.controller';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* @description 聊天总控制器(模态框模式)
|
|
7
|
+
* @author tony001
|
|
8
|
+
* @date 2026-05-15 14:05:54
|
|
9
|
+
* @export
|
|
10
|
+
* @class ModalChatController
|
|
11
|
+
* @extends {ChatBaseController}
|
|
12
|
+
*/
|
|
13
|
+
export declare class ModalChatController extends ChatBaseController {
|
|
14
|
+
/**
|
|
15
|
+
* @description 聊天框容器
|
|
16
|
+
* @author tony001
|
|
17
|
+
* @date 2026-05-15 13:05:46
|
|
18
|
+
* @protected
|
|
19
|
+
* @type {HTMLDivElement}
|
|
20
|
+
* @memberof ModalChatController
|
|
21
|
+
*/
|
|
22
|
+
protected container?: HTMLDivElement;
|
|
23
|
+
/**
|
|
24
|
+
* @description 创建容器，渲染loading状态
|
|
25
|
+
* @author tony001
|
|
26
|
+
* @date 2026-05-15 14:05:47
|
|
27
|
+
* @protected
|
|
28
|
+
* @param {IContainerOptions} opts
|
|
29
|
+
* @param {Record<string, any>} chatOptions
|
|
30
|
+
* @memberof ModalChatController
|
|
31
|
+
*/
|
|
32
|
+
protected setupContainer(opts: IContainerOptions, chatOptions: Record<string, any>): void;
|
|
33
|
+
/**
|
|
34
|
+
* @description 渲染正式聊天内容
|
|
35
|
+
* @author tony001
|
|
36
|
+
* @date 2026-05-15 14:05:02
|
|
37
|
+
* @protected
|
|
38
|
+
* @param {IContainerOptions} opts
|
|
39
|
+
* @param {Record<string, any>} chatOptions
|
|
40
|
+
* @param {AiChatController} aiChat
|
|
41
|
+
* @memberof ModalChatController
|
|
42
|
+
*/
|
|
43
|
+
protected renderChatContent(opts: IContainerOptions, chatOptions: Record<string, any>, aiChat: AiChatController): void;
|
|
44
|
+
/**
|
|
45
|
+
* @description 渲染切换后的内容
|
|
46
|
+
* @author tony001
|
|
47
|
+
* @date 2026-05-15 14:05:38
|
|
48
|
+
* @protected
|
|
49
|
+
* @param {Record<string, any>} opts
|
|
50
|
+
* @param {AiChatController} aiChat
|
|
51
|
+
* @memberof ModalChatController
|
|
52
|
+
*/
|
|
53
|
+
protected renderSwitchedContent(opts: Record<string, any>, aiChat: AiChatController): void;
|
|
54
|
+
/**
|
|
55
|
+
* @description 隐藏聊天窗口(必须先创建)
|
|
56
|
+
* @author tony001
|
|
57
|
+
* @date 2026-05-15 13:05:41
|
|
58
|
+
* @memberof ModalChatController
|
|
59
|
+
*/
|
|
60
|
+
hidden(): void;
|
|
61
|
+
/**
|
|
62
|
+
* @description 显示聊天窗窗口(必须先创建)
|
|
63
|
+
* @author tony001
|
|
64
|
+
* @date 2026-05-15 13:05:53
|
|
65
|
+
* @memberof ModalChatController
|
|
66
|
+
*/
|
|
67
|
+
show(): void;
|
|
68
|
+
/**
|
|
69
|
+
* @description 关闭聊天窗口
|
|
70
|
+
* @author tony001
|
|
71
|
+
* @date 2026-05-15 13:05:06
|
|
72
|
+
* @memberof ModalChatController
|
|
73
|
+
*/
|
|
74
|
+
close(): void;
|
|
75
|
+
}
|
|
76
|
+
declare const chat: ModalChatController;
|
|
77
|
+
export { chat };
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
export { AiChatController } from './ai-chat/ai-chat.controller';
|
|
2
2
|
export { AiTopicController } from './ai-topic/ai-topic.controller';
|
|
3
3
|
export { AIMaterialFactory } from './ai-material/ai-material-factory';
|
|
4
|
-
export {
|
|
4
|
+
export { ModalChatController, chat } from './chat/modal-chat.controller';
|
|
5
|
+
export { FlatChatController, createFlatChat, } from './chat/flat-chat.controller';
|
package/dist/types/index.d.ts
CHANGED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { AiChatController } from '../../controller';
|
|
2
|
+
import { ChatTopic } from '../../entity';
|
|
3
|
+
import { IContainerOptions } from '../i-container-options/i-container-options';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* @description 聊天总控制器接口
|
|
7
|
+
* @author tony001
|
|
8
|
+
* @date 2026-05-15 13:05:54
|
|
9
|
+
* @export
|
|
10
|
+
* @interface IChatController
|
|
11
|
+
*/
|
|
12
|
+
export interface IChatController {
|
|
13
|
+
/**
|
|
14
|
+
* @description 创建聊天窗口(会同时显示出来)
|
|
15
|
+
* @author tony001
|
|
16
|
+
* @date 2026-05-15 14:05:07
|
|
17
|
+
* @param {IContainerOptions} opts
|
|
18
|
+
* @returns {*} {Promise<AiChatController>}
|
|
19
|
+
* @memberof IChatController
|
|
20
|
+
*/
|
|
21
|
+
create(opts: IContainerOptions): Promise<AiChatController>;
|
|
22
|
+
/**
|
|
23
|
+
* @description 切换聊天控制器
|
|
24
|
+
* @author tony001
|
|
25
|
+
* @date 2026-05-15 14:05:37
|
|
26
|
+
* @param {ChatTopic} topic
|
|
27
|
+
* @memberof IChatController
|
|
28
|
+
*/
|
|
29
|
+
switchAiChatController(topic: ChatTopic): void;
|
|
30
|
+
}
|
|
@@ -19,3 +19,4 @@ export type { IChatUIAction } from './i-chat-uiaction/i-chat-uiaction';
|
|
|
19
19
|
export type { IKnowledgeBase } from './i-knowledge-base/i-knowledge-base';
|
|
20
20
|
export type { IConfirmUtil, IConfirmParams, INotificationUtil, INotificationParams, IMessageUtil, IMessageParams, } from './util';
|
|
21
21
|
export type { IChatMessageUsage } from './i-chat-message-usage/i-chat-message-usage';
|
|
22
|
+
export type { IChatController } from './i-chat-controller/i-chat-controller';
|
|
@@ -0,0 +1,399 @@
|
|
|
1
|
+
<!-- meta: date=2026-05-18 commit=083d062 branch=main -->
|
|
2
|
+
|
|
3
|
+
# 架构文档
|
|
4
|
+
|
|
5
|
+
## 第一章：项目定位
|
|
6
|
+
|
|
7
|
+
`@ibiz-template-plugin/ai-chat` 是一款深度集成于 iBiz 设计平台的 AI 智能辅助**插件**，以 npm 包形式发布，宿主应用通过 `chat.create()` 挂载聊天窗口到 DOM。插件基于 iBiz 模板引擎体系，通过 `peerDependencies` 声明对 `cherry-markdown`、`interactjs`、`qx-util` 的依赖，确保与宿主版本一致。
|
|
8
|
+
|
|
9
|
+
核心能力：
|
|
10
|
+
- 双呈现模式：模态框模式（可拖拽/缩放/最小化/全屏浮动窗口）和平铺模式（嵌入宿主容器，铺满外部元素）
|
|
11
|
+
- SSE 流式消息传输，支持思维链（think）、工具调用（tool_call）、步骤链（chatstep）、界面行为（chatuiaction）四种扩展消息类型
|
|
12
|
+
- 多话题管理（DEFAULT 单会话 / TOPIC 多话题切换），支持临时会话、置顶、重命名
|
|
13
|
+
- 双存储模式：LOCAL（IndexedDB 本地持久化）和 REMOTE（远程 API 会话管理）
|
|
14
|
+
- AI 智能体切换与知识库选择，支持召回参数配置
|
|
15
|
+
- 多模态素材上传（OSS 文件、业务实体数据），以 XML 协议附加到提问内容
|
|
16
|
+
- Markdown / 富文本渲染、代码高亮、预定义协议跳转、推荐提示
|
|
17
|
+
- i18n 国际化（中文 / 英文），资源使用量统计（token + 工具调用次数）
|
|
18
|
+
- 消息回填（backfill）、重新编辑、点赞 / 点踩反馈
|
|
19
|
+
|
|
20
|
+
## 第二章：架构图
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
24
|
+
│ 宿主应用 (iBiz) │
|
|
25
|
+
│ chat.create() / createFlatChat().create() │
|
|
26
|
+
└───────┬──────────────────────────────────┬───────────────────────┘
|
|
27
|
+
│ │
|
|
28
|
+
v v
|
|
29
|
+
┌───────────────────┐ ┌───────────────────┐
|
|
30
|
+
│ ModalChatController│ │ FlatChatController │
|
|
31
|
+
│ (chat 单例) │ │ (createFlatChat) │
|
|
32
|
+
│ 模态框/浮动窗口 │ │ 平铺/嵌入宿主容器 │
|
|
33
|
+
│ hidden/show/close │ │ close │
|
|
34
|
+
└────┬──────────────┘ └────┬──────────────┘
|
|
35
|
+
│ └──────┬────────────────┘
|
|
36
|
+
│ │
|
|
37
|
+
│ v
|
|
38
|
+
│ ┌──────────────────────┐
|
|
39
|
+
│ │ ChatBaseController │
|
|
40
|
+
│ │ (抽象基类) │
|
|
41
|
+
│ │ create/close/ │
|
|
42
|
+
│ │ switchAiChatController│
|
|
43
|
+
│ └──────────┬───────────┘
|
|
44
|
+
│ │
|
|
45
|
+
v v
|
|
46
|
+
┌──────────────────────────────────────────────┐
|
|
47
|
+
│ 控制器层 (Controller) │
|
|
48
|
+
│ ┌─────────────┐ ┌──────────────────┐ │
|
|
49
|
+
│ │ AiTopic │ │ AiChatController │ │
|
|
50
|
+
│ │ Controller │ │ (消息/素材/提问/ │ │
|
|
51
|
+
│ │ (话题CRUD/ │ │ 回填/智能体/ │ │
|
|
52
|
+
│ │ 切换/同步) │ │ 知识库/反馈) │ │
|
|
53
|
+
│ └──────┬──────┘ └────────┬─────────┘ │
|
|
54
|
+
│ │ │ │
|
|
55
|
+
│ v v │
|
|
56
|
+
│ ┌────────────────────────────────────┐ │
|
|
57
|
+
│ │ IChatOptions (宿主回调协议) │ │
|
|
58
|
+
│ └────────────────────────────────────┘ │
|
|
59
|
+
└──────────────────────────────────────────────┘
|
|
60
|
+
│
|
|
61
|
+
v
|
|
62
|
+
┌──────────────────────────────────────────┐
|
|
63
|
+
│ Preact 渲染层 │
|
|
64
|
+
│ ┌──────────────┐ ┌───────────────────┐ │
|
|
65
|
+
│ │ ChatContainer│ │FlatChatContainer │ │
|
|
66
|
+
│ │ (模态框容器) │ │(平铺容器) │ │
|
|
67
|
+
│ └──────┬───────┘ └────────┬──────────┘ │
|
|
68
|
+
│ │ │ │
|
|
69
|
+
│ v v │
|
|
70
|
+
│ ┌────────────────────────────────────┐ │
|
|
71
|
+
│ │ ChatMessages / ChatInput / │ │
|
|
72
|
+
│ │ ChatToolbar / ChatTopics ... │ │
|
|
73
|
+
│ └────────────────────────────────────┘ │
|
|
74
|
+
└──────────────────────────────────────────┘
|
|
75
|
+
│
|
|
76
|
+
v
|
|
77
|
+
┌──────────────────────────────────────────┐
|
|
78
|
+
│ 数据持久层 │
|
|
79
|
+
│ ┌──────────────┐ ┌───────────────────┐ │
|
|
80
|
+
│ │ IndexedDB │ │ IResourceOptions │ │
|
|
81
|
+
│ │ (LOCAL模式) │ │ (REMOTE模式API) │ │
|
|
82
|
+
│ └──────────────┘ └───────────────────┘ │
|
|
83
|
+
└──────────────────────────────────────────┘
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
图例：`-->` 同步调用 / 数据流，组件间为 Preact props 传递。
|
|
87
|
+
|
|
88
|
+
## 第三章：核心架构说明
|
|
89
|
+
|
|
90
|
+
**分层策略**：项目采用三层架构——控制器层（业务逻辑）、UI 组件层（Preact 渲染）、数据持久层（IndexedDB / 远程 API）。控制器持有全部状态，UI 层通过 `@preact/signals` 响应式更新，数据层由控制器按 `resourceMode` 路由到 LOCAL 或 REMOTE 实现。
|
|
91
|
+
|
|
92
|
+
**控制器协作**：`ChatBaseController` 是抽象基类，封装了通用的 `create()` / `close()` / `switchAiChatController()` 流程及 `AiTopicController` 管理，子类仅需实现容器创建与渲染的三个抽象方法（`setupContainer` / `renderChatContent` / `renderSwitchedContent`）。`ModalChatController`（`chat` 单例）继承基类，实现模态框/浮动窗口模式，在 body 上创建独立 DOM 容器，支持拖拽/缩放/全屏/最小化/隐藏/显示；`FlatChatController`（`createFlatChat()` 工厂函数创建，支持多实例）继承基类，实现平铺嵌入模式，渲染到宿主指定的 `container` 元素内，铺满容器且无窗口控制。`AiTopicController` 管理话题列表的 CRUD、激活切换和持久化，通过 `IChatController` 接口与基类解耦。`AiChatController` 是核心业务控制器，管理消息流、素材、智能体切换、知识库选择、提问 / 中断 / 回填等完整生命周期。
|
|
93
|
+
|
|
94
|
+
**数据流向**：用户输入 → `AiChatController.question()` → 拼接素材资源 XML → `IChatOptions.question()` 回调（宿主实现 SSE 请求） → 流式 `addMessage` / `replaceMessage` 更新 Signal → Preact 自动重渲染 → `completeMessage` 完成时触发回填 / 推荐提示 / 话题标题更新 → `asyncToIndexDB` 持久化。
|
|
95
|
+
|
|
96
|
+
**状态管理**：全部使用 `@preact/signals` 的 `signal()` 细粒度响应式，无全局 Store。每个控制器将核心状态声明为 `readonly Signal<T>`，UI 组件通过 `.value` 读写，变更后通过 `[...array]` 创建新引用触发更新。
|
|
97
|
+
|
|
98
|
+
**宿主集成**：插件不直接发起 HTTP 请求，所有 AI 交互通过 `IChatOptions` 回调协议委托给宿主（`question`、`history`、`abortQuestion`、`action`、`backfill`、`chatDigest`、`recommendPrompt` 等），插件仅负责 UI 呈现和本地状态管理。
|
|
99
|
+
|
|
100
|
+
## 第四章：项目结构
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
src/
|
|
104
|
+
├── index.ts # 插件入口，导出 ChatContainer、FlatChatContainer、chat、createFlatChat、IChatToolbarItem
|
|
105
|
+
├── index.scss # 全局样式入口
|
|
106
|
+
├── global.ts # PluginStaticResource 静态资源路径实例
|
|
107
|
+
├── main.tsx # 开发调试入口（非发布入口）
|
|
108
|
+
├── app.tsx # 开发调试应用组件
|
|
109
|
+
├── constants/
|
|
110
|
+
│ └── index.ts # AIChatConst 枚举：缓存key、数据库名/表名
|
|
111
|
+
├── controller/
|
|
112
|
+
│ ├── index.ts # 导出：AiChatController、AiTopicController、AIMaterialFactory、ModalChatController/chat、FlatChatController/createFlatChat
|
|
113
|
+
│ ├── chat/
|
|
114
|
+
│ │ ├── chat-base.controller.ts # ChatBaseController：抽象基类，封装create/close/switch流程
|
|
115
|
+
│ │ ├── modal-chat.controller.ts # ModalChatController(chat单例)：模态框/浮动窗口模式
|
|
116
|
+
│ │ └── flat-chat.controller.ts # FlatChatController(createFlatChat)：平铺嵌入模式，支持多实例
|
|
117
|
+
│ ├── ai-chat/
|
|
118
|
+
│ │ └── ai-chat.controller.ts # AiChatController：消息管理、提问/中断/回填/反馈、智能体/知识库
|
|
119
|
+
│ ├── ai-topic/
|
|
120
|
+
│ │ └── ai-topic.controller.ts # AiTopicController：话题CRUD、切换、同步远程会话
|
|
121
|
+
│ └── ai-material/
|
|
122
|
+
│ └── ai-material-factory.ts # AIMaterialFactory：素材帮助器工厂（Common/File）
|
|
123
|
+
├── components/
|
|
124
|
+
│ ├── index.ts # 导出：ChatContainer、FlatChatContainer
|
|
125
|
+
│ ├── chat-container/ # 模态框聊天容器：拖拽、缩放、全屏、最小化、侧边栏布局
|
|
126
|
+
│ ├── flat-chat-container/ # 平铺聊天容器：嵌入宿主容器，铺满外部元素，无窗口控制
|
|
127
|
+
│ ├── chat-messages/ # 消息列表：无限滚动、自动滚底、批量加载
|
|
128
|
+
│ ├── chat-message-item/ # 消息项：按角色渲染（Markdown/用户/错误/未知）
|
|
129
|
+
│ │ ├── markdown-message/ # AI Markdown 消息渲染（cherry-markdown）
|
|
130
|
+
│ │ ├── user-message/ # 用户消息渲染
|
|
131
|
+
│ │ ├── error-message/ # 错误消息渲染
|
|
132
|
+
│ │ └── unknown-message/ # 未知类型消息兜底
|
|
133
|
+
│ ├── chat-input/ # 输入框：Tiptap编辑器、语音、文件上传、智能体/知识库选择
|
|
134
|
+
│ ├── chat-input-material/ # 素材列表容器
|
|
135
|
+
│ ├── chat-input-material-item/ # 素材项（通用/ossfile两种）
|
|
136
|
+
│ ├── chat-toolbar/ # 消息工具栏
|
|
137
|
+
│ ├── chat-toolbar/chat-toolbar-item/ # 工具栏项
|
|
138
|
+
│ ├── chat-think/ # 思维链展示（可折叠）
|
|
139
|
+
│ ├── chat-step/ # 步骤链展示
|
|
140
|
+
│ ├── chat-step-item/ # 步骤项
|
|
141
|
+
│ ├── chat-tool-call/ # 工具调用展示
|
|
142
|
+
│ ├── chat-tool-call-item/ # 工具调用项（chunk/image/default三种）
|
|
143
|
+
│ ├── chat-suggestions/ # 推荐提示列表
|
|
144
|
+
│ ├── chat-search/ # 话题搜索
|
|
145
|
+
│ ├── chat-topics/ # 话题侧边栏列表
|
|
146
|
+
│ ├── chat-topic-item/ # 话题项
|
|
147
|
+
│ ├── chat-back-bottom/ # 回到底部按钮
|
|
148
|
+
│ ├── chat-minimize/ # 最小化浮球
|
|
149
|
+
│ ├── chat-agent-setting/ # 智能体设置面板
|
|
150
|
+
│ ├── chat-editor/ # 编辑器组件
|
|
151
|
+
│ ├── chat-image-preview/ # 图片预览
|
|
152
|
+
│ ├── popup/ # 气泡弹框
|
|
153
|
+
│ └── common/ # 公共组件：loading、消息工具栏、多选、单选、滑块、开关
|
|
154
|
+
├── entity/
|
|
155
|
+
│ ├── index.ts # 导出：ChatMessage、ChatTopic、ChatMaterial、ChatSuggestion、AIAgent、KnowledgeBase
|
|
156
|
+
│ ├── chat-message/ # ChatMessage：消息实体，update/replace/complete逻辑
|
|
157
|
+
│ ├── chart-topic/ # ChatTopic：话题实体
|
|
158
|
+
│ ├── chart-material/ # ChatMaterial：素材实体
|
|
159
|
+
│ ├── chat-suggestion/ # ChatSuggestion：推荐提示实体
|
|
160
|
+
│ ├── ai-agent/ # AIAgent：智能体实体（含召回配置）
|
|
161
|
+
│ └── knowledge-base/ # KnowledgeBase：知识库实体
|
|
162
|
+
├── interface/ # 全部接口/类型定义（共19个子目录）
|
|
163
|
+
│ ├── index.ts # 聚合导出全部接口
|
|
164
|
+
│ ├── i-chat-options/ # IChat / IChatOptions：宿主回调协议
|
|
165
|
+
│ ├── i-chat-controller/ # IChatController：聊天总控制器接口
|
|
166
|
+
│ ├── i-chat-container/ # IChatContainerOptions / IAutoClose
|
|
167
|
+
│ ├── i-chat-message/ # IChatMessage：消息结构
|
|
168
|
+
│ ├── i-chat-message-usage/ # IChatMessageUsage：token使用量
|
|
169
|
+
│ ├── i-chat-tool-call/ # IChatToolCall：工具调用
|
|
170
|
+
│ ├── i-chat-think/ # IChatThink：思维链
|
|
171
|
+
│ ├── i-chat-step/ # IChatStep：步骤链
|
|
172
|
+
│ ├── i-chat-suggestion/ # IChatSuggestion：推荐提示
|
|
173
|
+
│ ├── i-chat-uiaction/ # IChatUIAction：界面行为
|
|
174
|
+
│ ├── i-chat-toolbar-item/ # IChatToolbarItem：工具栏项
|
|
175
|
+
│ ├── i-message-item-provider/ # IMessageItemProvider：自定义消息渲染
|
|
176
|
+
│ ├── i-ai-agent/ # IAIAgent / IAIAgentConfig：智能体配置
|
|
177
|
+
│ ├── i-knowledge-base/ # IKnowledgeBase：知识库
|
|
178
|
+
│ ├── i-material/ # IMaterial：素材
|
|
179
|
+
│ ├── i-resource-options/ # IResourceOptions：远程资源API协议
|
|
180
|
+
│ ├── i-config-service/ # IConfigService：配置存储服务
|
|
181
|
+
│ ├── i-remote-resource/ # IRemoteSession / IRemoteMessage
|
|
182
|
+
│ ├── i-file-uploader-options/ # FileUploaderOptions
|
|
183
|
+
│ ├── i-container-options/ # IContainerOptions
|
|
184
|
+
│ ├── i-topic-options/ # ITopic / ITopicOptions
|
|
185
|
+
│ └── util/ # INotificationUtil / IMessageUtil / IConfirmUtil
|
|
186
|
+
├── utils/
|
|
187
|
+
│ ├── index.ts # 聚合导出全部工具
|
|
188
|
+
│ ├── util/ # 通用工具：UUID、html2md/md2html、剪贴板、解析协议、IndexedDB、文件上传、素材解析
|
|
189
|
+
│ │ ├── util.ts # createUUID, html2md, md2html, parsePredefProtocol, TextUtil, getChatSessionId
|
|
190
|
+
│ │ ├── indexdb-util.ts # IndexedDBUtil：表检查/创建/CRUD
|
|
191
|
+
│ │ ├── file-uploader.ts # FileUploader：文件上传
|
|
192
|
+
│ │ ├── material-resource-parser.ts # MaterialResourceParser：素材XML序列化/反序列化
|
|
193
|
+
│ │ ├── chat-suggestion-parser.ts # ChatSuggestionParser：推荐提示解析
|
|
194
|
+
│ │ ├── chat-tool-call-parser.ts # ChatToolCallParser：工具调用解析
|
|
195
|
+
│ │ ├── chat-step-parser.ts # ChatStepParser：步骤链解析
|
|
196
|
+
│ │ ├── chat-ui-action-parser.ts # ChatUIActionParser：界面行为解析
|
|
197
|
+
│ │ ├── drag-util.ts # isWithinBounds, limitDraggable：拖拽边界工具
|
|
198
|
+
│ │ └── text-hash-util.ts # generateHashWithText：文本哈希
|
|
199
|
+
│ └── plugin-static-resource/ # PluginStaticResource：插件静态资源路径计算
|
|
200
|
+
├── icons/ # SVG图标组件（约40个）
|
|
201
|
+
└── locale/
|
|
202
|
+
├── index.ts # i18n 实例，支持 setLanguage/setLocale
|
|
203
|
+
├── zh-CN/ # 中文语言包
|
|
204
|
+
└── en/ # 英文语言包
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## 第五章：功能清单
|
|
208
|
+
|
|
209
|
+
### 注册与初始化
|
|
210
|
+
|
|
211
|
+
| 功能 | 说明 | 关键文件 | 状态 |
|
|
212
|
+
|------|------|----------|------|
|
|
213
|
+
| 模态框窗口创建 | `chat.create(opts)` 挂载浮动窗口到 body | `src/controller/chat/modal-chat.controller.ts` | 稳定 |
|
|
214
|
+
| 平铺窗口创建 | `createFlatChat().create(opts)` 嵌入宿主容器 | `src/controller/chat/flat-chat.controller.ts` | 稳定 |
|
|
215
|
+
| 控制器抽象基类 | ChatBaseController 封装通用 create/close/switch 流程 | `src/controller/chat/chat-base.controller.ts` | 稳定 |
|
|
216
|
+
| 资源模式切换 | LOCAL（IndexedDB）/ REMOTE（远程API）双模式 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
217
|
+
| 智能体清单加载 | 内部获取或宿主传入 AI Agent 列表 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
218
|
+
| 知识库初始化 | 按智能体过滤可用知识库并默认选中 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
219
|
+
| 窗口样式缓存 | localStorage 持久化窗口位置/尺寸 | `src/components/chat-container/chat-container.tsx` | 稳定 |
|
|
220
|
+
|
|
221
|
+
### 运行时钩子
|
|
222
|
+
|
|
223
|
+
| 功能 | 说明 | 关键文件 | 状态 |
|
|
224
|
+
|------|------|----------|------|
|
|
225
|
+
| 提问与流式响应 | 调用宿主 question 回调，流式 addMessage/replaceMessage | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
226
|
+
| 中断请求 | abortQuestion 回调宿主中断 SSE | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
227
|
+
| 思维链展示 | 解析 `<think>` 标签，可折叠展示推理过程 | `src/components/chat-think/` | 稳定 |
|
|
228
|
+
| 工具调用展示 | 解析 `<tool_call>` 标签，支持 chunk/image/default 三种类型 | `src/components/chat-tool-call/` | 稳定 |
|
|
229
|
+
| 步骤链展示 | 解析 `<chatstep>` 标签，步骤式展示 | `src/components/chat-step/` | 稳定 |
|
|
230
|
+
| 界面行为 | 解析 `<chatuiaction>` 标签，支持 view/action 跳转 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
231
|
+
| 推荐提示 | AI 回答完成后异步获取推荐问题 | `src/components/chat-suggestions/` | 稳定 |
|
|
232
|
+
| 消息回填 | AI 回答完成时自动或手动回填到宿主表单 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
233
|
+
| 点赞/点踩 | 消息反馈，调用远程 API | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
234
|
+
| 重新编辑 | 用户消息支持重新编辑并重新提交 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
235
|
+
| 消息刷新 | 删除当前及后续消息，重新提问 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
236
|
+
| 资源使用量统计 | 消息 token 消耗量及工具调用次数 | `src/interface/i-chat-message-usage/` | 稳定 |
|
|
237
|
+
|
|
238
|
+
### 资源清理
|
|
239
|
+
|
|
240
|
+
| 功能 | 说明 | 关键文件 | 状态 |
|
|
241
|
+
|------|------|----------|------|
|
|
242
|
+
| 窗口关闭 | 模态框：移除 DOM；平铺：清空容器。均销毁所有 AiChatController | `src/controller/chat/modal-chat.controller.ts`、`src/controller/chat/flat-chat.controller.ts` | 稳定 |
|
|
243
|
+
| 对话清空 | 清除消息并删除 IndexedDB / 远程会话数据 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
244
|
+
| 话题删除 | 删除单话题及关联数据，自动切换 | `src/controller/ai-topic/ai-topic.controller.ts` | 稳定 |
|
|
245
|
+
| 批量清空话题 | 保留激活话题，删除其余全部 | `src/controller/ai-topic/ai-topic.controller.ts` | 稳定 |
|
|
246
|
+
|
|
247
|
+
### 配置管理
|
|
248
|
+
|
|
249
|
+
| 功能 | 说明 | 关键文件 | 状态 |
|
|
250
|
+
|------|------|----------|------|
|
|
251
|
+
| 多话题模式 | TOPIC 模式侧边栏切换，DEFAULT 单会话 | `src/controller/ai-topic/ai-topic.controller.ts` | 稳定 |
|
|
252
|
+
| 临时会话 | 禁用存储的一次性对话 | `src/controller/ai-topic/ai-topic.controller.ts` | 稳定 |
|
|
253
|
+
| 智能体切换 | 切换 Agent 并同步召回配置/知识库 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
254
|
+
| 知识库选择 | 多选知识库，按智能体过滤可用范围 | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
255
|
+
| 话题标题计算 | snippet 截取 / summary AI 摘要 / default | `src/controller/ai-chat/ai-chat.controller.ts` | 稳定 |
|
|
256
|
+
| 素材上传 | 文件/实体数据以 XML 协议附加到提问 | `src/utils/util/material-resource-parser.ts` | 稳定 |
|
|
257
|
+
| 自定义消息渲染 | IMessageItemProvider 扩展消息类型 | `src/interface/i-message-item-provider/` | 实验性 |
|
|
258
|
+
|
|
259
|
+
## 第六章：架构决策记录（ADR）
|
|
260
|
+
|
|
261
|
+
| 决策编号 | 决策标题 | 状态 | 上下文 | 决策结果 | 取舍 | 决策依据来源 |
|
|
262
|
+
|----------|----------|------|--------|----------|------|--------------|
|
|
263
|
+
| ADR-001 | UI 框架选型 | 已采纳 | 需要轻量级渲染方案嵌入宿主 DOM | Preact + Signals | 放弃 React（体积大，与宿主可能冲突）；放弃 Vue（宿主非 Vue 生态） | 推断（package.json 仅含 preact 依赖） |
|
|
264
|
+
| ADR-002 | AI 交互委托宿主 | 已采纳 | 插件不应直接耦合后端 API | IChatOptions 回调协议 | 插件无法独立运行，宿主需实现完整 AI 请求逻辑 | 代码注释 + 接口设计 |
|
|
265
|
+
| ADR-003 | 双存储模式 | 已采纳 | 需支持离线场景和云端同步两种部署 | LOCAL(IndexedDB) + REMOTE(远程API) | 增加了控制器中的模式判断分支，但保持了灵活性 | 推断（IResourceOptions 接口设计） |
|
|
266
|
+
| ADR-004 | 消息扩展协议基于 XML 标签 | 已采纳 | AI 回复需携带结构化数据（步骤、行为、工具调用） | 自定义 XML 标签（\<think\>、\<chatstep\>、\<chatuiaction\>、\<tool_call\>） | 解析可靠性依赖严格标签匹配，但避免了 JSON-in-Markdown 的转义问题 | 推断（ChatStepParser 等解析器实现） |
|
|
267
|
+
| ADR-005 | 双呈现模式：模态框 + 平铺 | 已采纳 | 宿主场景分化：独立浮动窗口 vs 嵌入页面区域，需支持不同布局模式 | ChatBaseController 抽象基类 + ModalChatController / FlatChatController 子类继承 | 增加了控制器层级，但实现了模式间代码复用（基类统一 create/switch 流程），平铺模式支持多实例 | 代码注释 + 控制器重构（chat.controller.ts 拆分为三个文件） |
|
|
268
|
+
|
|
269
|
+
## 第七章：对外接口与配置
|
|
270
|
+
|
|
271
|
+
### 插件注册入口
|
|
272
|
+
|
|
273
|
+
| 接口 / 类 | 说明 | 关键参数 | 返回值 / 类型 | 可见性 |
|
|
274
|
+
|---------|------|----------|---------|--------|
|
|
275
|
+
| `chat` | 模态框模式全局单例 | — | `ModalChatController` | 公开 API |
|
|
276
|
+
| `ModalChatController.create(opts)` | 创建并显示模态框聊天窗口 | `IContainerOptions` | `Promise<AiChatController>` | 公开 API |
|
|
277
|
+
| `ModalChatController.close()` | 关闭聊天窗口 | — | `void` | 公开 API |
|
|
278
|
+
| `ModalChatController.hidden()` | 隐藏窗口（不销毁） | — | `void` | 公开 API |
|
|
279
|
+
| `ModalChatController.show()` | 显示已隐藏的窗口 | — | `void` | 公开 API |
|
|
280
|
+
| `createFlatChat()` | 创建平铺模式聊天实例（支持多实例） | — | `FlatChatController` | 公开 API |
|
|
281
|
+
| `FlatChatController.create(opts)` | 在宿主容器内创建平铺聊天 | `IContainerOptions`（containerOptions.container 必填） | `Promise<AiChatController>` | 公开 API |
|
|
282
|
+
| `FlatChatController.close()` | 清空平铺聊天 | — | `void` | 公开 API |
|
|
283
|
+
| `ChatContainer` | 模态框容器组件 | `ChatContainerProps` | `Component` | 公开 API |
|
|
284
|
+
| `FlatChatContainer` | 平铺容器组件 | `FlatChatContainerProps` | `Component` | 公开 API |
|
|
285
|
+
| `IChatToolbarItem` | 工具栏项类型 | — | `Type` | 公开 API |
|
|
286
|
+
| `IChatController` | 聊天总控制器接口（create/switchAiChatController） | — | `Interface` | 公开 API |
|
|
287
|
+
|
|
288
|
+
### 宿主集成配置表
|
|
289
|
+
|
|
290
|
+
| 钩子 / 扩展点 | 触发时机 | 参数签名 | 返回值约束 |
|
|
291
|
+
|---------|---------|------|----------|
|
|
292
|
+
| `IChatOptions.question` | 用户发送提问 | `(aiChat, context, params, data, messages, sessionid, agentID, mode, scope, knowledgeBases, recallConfig, appendCurData, mcpservers)` | `Promise<void>` |
|
|
293
|
+
| `IChatOptions.history` | 初始化时加载历史 | `(context, params, data)` | `Promise<boolean>` |
|
|
294
|
+
| `IChatOptions.abortQuestion` | 用户中断请求 | `(aiChat, context, params, data)` | `Promise<void>` |
|
|
295
|
+
| `IChatOptions.action` | 消息行为回调 | `(action: string, data)` | `void` |
|
|
296
|
+
| `IChatOptions.backfill` | 消息回填 | `(message: IChatMessage)` | `void` |
|
|
297
|
+
| `IChatOptions.closed` | 窗口关闭回调 | `(context, params, messages)` | `void` |
|
|
298
|
+
| `IChatOptions.chatDigest` | 话题标题摘要 | `(context, params, data)` | `Promise<any>` |
|
|
299
|
+
| `IChatOptions.recommendPrompt` | 推荐提示获取 | `(context, params, data)` | `Promise<any>` |
|
|
300
|
+
| `IChatOptions.extendToolbarClick` | 扩展工具栏点击 | `(event, actionInfo, context, params, data)` | `Promise<any>` |
|
|
301
|
+
| `IChatOptions.openLinkView` | 预定义视图跳转 | `(url, message, event)` | `Promise<void>` |
|
|
302
|
+
| `IChatOptions.fetchAgentList` | 智能体清单获取 | `(query?: string)` | `Promise<IAIAgent[]>` |
|
|
303
|
+
| `IChatOptions.fetchKnowledgeBaseList` | 知识库清单获取 | — | `Promise<IKnowledgeBase[]>` |
|
|
304
|
+
| `IResourceOptions.getMessages` | 远程获取消息 | `(query)` | `Promise<IRemoteMessage[]>` |
|
|
305
|
+
| `IResourceOptions.getSessionList` | 远程获取会话列表 | `(query?)` | `Promise<IRemoteSession[]>` |
|
|
306
|
+
| `IResourceOptions.deleteSession` | 远程删除会话 | `(realid)` | `Promise<boolean>` |
|
|
307
|
+
| `IResourceOptions.updateSession` | 远程更新会话 | `(realid, data)` | `Promise<boolean>` |
|
|
308
|
+
| `IResourceOptions.deleteMessage` | 远程删除消息 | `(messageId)` | `Promise<boolean>` |
|
|
309
|
+
| `IConfigService` | 话题配置存储服务 | `(appid, key, type)` | `{save, load, reset}` |
|
|
310
|
+
|
|
311
|
+
## 第八章：技术栈
|
|
312
|
+
|
|
313
|
+
| 类别 | 技术 | 版本 | 备注 / 选型原因 |
|
|
314
|
+
|------|------|------|------|
|
|
315
|
+
| UI 框架 | Preact | ^10.18.1 | 轻量 React 兼容，适合嵌入宿主 DOM |
|
|
316
|
+
| 状态管理 | @preact/signals | ^1.2.1 | 细粒度响应式，无需全局 Store |
|
|
317
|
+
| 构建工具 | Vite | ^4.5.0 | 库模式构建，dts 类型生成 |
|
|
318
|
+
| Markdown 渲染 | cherry-markdown | 0.8.58 | peerDep，宿主提供，支持代码高亮 |
|
|
319
|
+
| 富文本编辑器 | @tiptap/core + extensions | ^3.11.1 | 输入框富文本编辑 |
|
|
320
|
+
| 拖拽交互 | interactjs | ^1.10.19 | peerDep，窗口拖拽/缩放 |
|
|
321
|
+
| 样式预处理 | Sass | ^1.69.5 | BEM 命名 + @ibiz-template/scss-utils |
|
|
322
|
+
| 类型生成 | vite-plugin-dts | ^3.6.3 | 构建时生成 .d.ts |
|
|
323
|
+
| 代码规范 | ESLint + Prettier + Stylelint | — | airbnb-base 规则集 |
|
|
324
|
+
| 提交规范 | commitlint + husky + lint-staged | — | conventional 规范 |
|
|
325
|
+
| TypeScript | ^5.2.2 | | |
|
|
326
|
+
| 国际化 | 自研 i18n 模块 | — | zh-CN / en |
|
|
327
|
+
|
|
328
|
+
运行环境要求：Node.js >= 16，pnpm 包管理器，浏览器需支持 ES2020+、IndexedDB、Fullscreen API。
|
|
329
|
+
|
|
330
|
+
## 第九章：开发指南
|
|
331
|
+
|
|
332
|
+
### 常用命令
|
|
333
|
+
|
|
334
|
+
| 命令 | 说明 | 适用范围 |
|
|
335
|
+
|------|------|----------|
|
|
336
|
+
| `pnpm install` | 安装依赖 | 全局 |
|
|
337
|
+
| `pnpm dev` | 启动开发服务（port 5174） | 全局 |
|
|
338
|
+
| `pnpm build` | 生产构建（ES + Legacy + d.ts + CSS） | 全局 |
|
|
339
|
+
| `pnpm build:watch` | 监听模式构建 | 全局 |
|
|
340
|
+
| `pnpm preview` | 预览构建产物 | 全局 |
|
|
341
|
+
| `pnpm publish:npm` | 构建并发布到 npm latest | 全局 |
|
|
342
|
+
| `pnpm publish:next` / `dev` / `beta` | 构建并发布到 npm 对应 tag | 全局 |
|
|
343
|
+
|
|
344
|
+
### 本地调试
|
|
345
|
+
|
|
346
|
+
1. 执行 `pnpm build:watch` 启动监听构建
|
|
347
|
+
2. 执行 `pnpm link --global` 将包链接到全局
|
|
348
|
+
3. 在宿主项目中执行 `pnpm link --global "@ibiz-template-plugin/ai-chat"` 链接插件
|
|
349
|
+
4. 修改源码后自动重新构建，宿主项目需刷新页面生效
|
|
350
|
+
|
|
351
|
+
### 环境变量
|
|
352
|
+
|
|
353
|
+
无需环境变量配置，插件通过 `IChatOptions` / `IResourceOptions` 回调协议接收全部运行时配置。
|
|
354
|
+
|
|
355
|
+
## 第十章：关键时序
|
|
356
|
+
|
|
357
|
+
### 插件生命周期时序
|
|
358
|
+
|
|
359
|
+
```
|
|
360
|
+
宿主应用 ModalChatController AiTopicController AiChatController 宿主回调
|
|
361
|
+
| | | | |
|
|
362
|
+
|--chat.create()--> | | | |
|
|
363
|
+
| |--setupContainer()---->| | |
|
|
364
|
+
| | (创建DOM+渲染Loading)| | |
|
|
365
|
+
| | | | |
|
|
366
|
+
| |--fetchAgentList------>| |------获取智能体---->|
|
|
367
|
+
| |<---agentList----------| |<---智能体清单-------|
|
|
368
|
+
| | | | |
|
|
369
|
+
| |--初始化AiChatController| | |
|
|
370
|
+
| | | new AiChatController(opts) |
|
|
371
|
+
| | | |--initAIChat()----->|
|
|
372
|
+
| | | | |--history()---->|
|
|
373
|
+
| | | | |<--历史数据------|
|
|
374
|
+
| |--renderChatContent()->| | |
|
|
375
|
+
| | (渲染ChatContainer) | | |
|
|
376
|
+
|<--聊天窗口展示----| | | |
|
|
377
|
+
| | | | |
|
|
378
|
+
| | 用户输入问题 | |
|
|
379
|
+
| | | |--question()------>|
|
|
380
|
+
| | | | |--question()--->| (SSE请求)
|
|
381
|
+
| | | |<--addMessage流式---|
|
|
382
|
+
| | | |--completeMessage-->|
|
|
383
|
+
| | | |--asyncToIndexDB--->|
|
|
384
|
+
| | | |--updateTopicCaption|
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
平铺模式时序与模态框一致，区别在于入口为 `createFlatChat().create(opts)`，容器由宿主通过 `containerOptions.container` 提供，渲染 `FlatChatContainer` 而非 `ChatContainer`。
|
|
388
|
+
|
|
389
|
+
## 第十一章：注意事项与技术债
|
|
390
|
+
|
|
391
|
+
| 严重程度 | 问题描述 | 所在文件 | 修复成本 | 建议方案 |
|
|
392
|
+
|----------|----------|----------|----------|----------|
|
|
393
|
+
| 高 | AiChatController 近 2000 行，职责过多（消息/素材/智能体/知识库/反馈/回填/编辑），违反单一职责 | `src/controller/ai-chat/ai-chat.controller.ts` | 大 | 拆分为 MessageManager、MaterialManager、AgentManager 等子模块，AiChatController 做编排 |
|
|
394
|
+
| 中 | 大量 `@typescript-eslint/no-explicit-any` 禁用，`Record<string, any>` 泛滥 | `ai-chat.controller.ts`、`ai-topic.controller.ts`、`chat-base.controller.ts` | 中 | 为 topicOptions、chatOptions 内部流转补充接口定义，逐步收窄 any |
|
|
395
|
+
| 中 | handleSuggestionClick 和 handleUIActionClick 逻辑高度重复（action 分支代码几乎一致） | `src/controller/ai-chat/ai-chat.controller.ts:1482-1653` | 小 | 提取公共的 handleActionClick 方法，统一 action/raw 分支处理 |
|
|
396
|
+
| 中 | `as any` 类型断言遍布，如 `(suggestion.data as any).actionid`、`(metadata as any).content_name` | `ai-chat.controller.ts` | 中 | 为 IChatSuggestion.data / IChatUIAction.data 补充泛型或联合类型 |
|
|
397
|
+
| 中 | 常量拼写错误 `MINIMIZE_STYLY_CHCHE`（应为 STYLE_CACHE） | `src/constants/index.ts` | 小 | 修正拼写，全局替换引用 |
|
|
398
|
+
| 中 | ModalChatController / FlatChatController 中 props 构造高度重复（setupContainer / renderChatContent / renderSwitchedContent 三个方法中 props 对象几乎一致） | `modal-chat.controller.ts`、`flat-chat.controller.ts` | 中 | 在 ChatBaseController 中提取 buildContainerProps 方法，子类仅需覆盖差异部分 |
|
|
399
|
+
| 低 | 缺少单元测试和 E2E 测试 | 全项目 | 大 | 优先为核心控制器（AiChatController、AiTopicController）编写单元测试 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ibiz-template-plugin/ai-chat",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.84",
|
|
4
4
|
"description": "iBiz AI交互框插件",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.es.js",
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
"dist/index.min.css"
|
|
12
12
|
],
|
|
13
13
|
"files": [
|
|
14
|
+
"docs",
|
|
14
15
|
"dist",
|
|
15
16
|
"README.md"
|
|
16
17
|
],
|