sang-ai-kit 0.0.0-stage → 0.1.1
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/LICENSE +201 -0
- package/README.md +134 -3
- package/generated/sang-ai-utilities.css +4472 -0
- package/package.json +79 -5
- package/src/AiAssistant.tsx +966 -0
- package/src/AiChat.tsx +82 -0
- package/src/AiSettings.tsx +1438 -0
- package/src/ChatScrollbar.tsx +116 -0
- package/src/EncryptionKeySettings.tsx +568 -0
- package/src/FontSettings.tsx +507 -0
- package/src/ImageModelSettings.tsx +627 -0
- package/src/ModelControls.tsx +246 -0
- package/src/SessionList.tsx +1177 -0
- package/src/SkillSettings.tsx +724 -0
- package/src/TokenUsageBar.tsx +410 -0
- package/src/ToolDuration.tsx +31 -0
- package/src/assistant.css +1713 -0
- package/src/assistantTypes.ts +139 -0
- package/src/browserAiStore.ts +44 -0
- package/src/builtInTools.ts +76 -0
- package/src/configStore.ts +287 -0
- package/src/conversationUtils.ts +76 -0
- package/src/encryption.ts +51 -0
- package/src/endpointConnection.ts +37 -0
- package/src/features.ts +27 -0
- package/src/floatingGeometry.ts +16 -0
- package/src/fonts.ts +101 -0
- package/src/id.ts +4 -0
- package/src/image-generation/adapters/agnes.ts +24 -0
- package/src/image-generation/adapters/gptImage.ts +38 -0
- package/src/image-generation/adapters/kolors.ts +20 -0
- package/src/image-generation/index.ts +87 -0
- package/src/image-generation/models.ts +51 -0
- package/src/image-generation/results.ts +53 -0
- package/src/image-generation/types.ts +56 -0
- package/src/imageAttachments.ts +70 -0
- package/src/imageStore.ts +59 -0
- package/src/index.ts +43 -0
- package/src/modelConfig.ts +68 -0
- package/src/openai.ts +159 -0
- package/src/responses.ts +13 -0
- package/src/sessionTypes.ts +25 -0
- package/src/settingsTypes.ts +58 -0
- package/src/skills.ts +40 -0
- package/src/style.css +68 -0
- package/src/toolLoop.ts +50 -0
- package/src/useAssistant.ts +329 -0
- package/src/useChatScroll.ts +113 -0
- package/src/useFloatingPanel.ts +71 -0
- package/src/useResolvedTheme.ts +16 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright [yyyy] [name of copyright owner]
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,134 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# SangAIKit
|
|
2
|
+
|
|
3
|
+
SangAIKit 是面向 React 应用的通用 AI 助手组件与能力包,包含浮窗、配置中心、会话列表、图片画廊、模型选择、SKILL、字体管理、生图协议、密钥管理和用量面板。宿主应用通过适配器接入自己的工作区与业务工具。
|
|
4
|
+
|
|
5
|
+
## 运行演示
|
|
6
|
+
|
|
7
|
+
需要 Bun、Node.js(Vite 7 要求 20.19+ 或 22.12+)及现代浏览器。
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
bun install
|
|
11
|
+
bun run dev
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
演示支持会话新建、切换、重命名和删除、窗口拖动及缩放、多端点模型、图片附件、SKILL、生图、工具步骤、用量、浅色和深色。工作区中的接入配置面板可实时切换宿主功能、调整调用上限,并预览实际注册的工具;模型与限制保存在配置存储,接入开关单独保存在浏览器 localStorage。演示初始不添加生图模型;需在 AI 配置中心的“生图模型”页手动选择预设、绑定端点并启用,之后才会注册生图工具。使用真实模型发送请求后,可在工作区展开“最近的实际网络请求”,查看实际 URL、最终 instructions、工具签名和请求 JSON;图片 Base64 会脱敏,本地模拟回复不会产生网络请求。默认模型使用模拟回复和模拟工具,不访问远端;会话文本保存在浏览器 localStorage,图片保存在 IndexedDB。选择真实模型并配置兼容 Responses API 的端点后,可调用真实模型及配置的生图服务,可能产生费用。
|
|
15
|
+
|
|
16
|
+
演示将配置和 AES-GCM 加密后的 API Key 保存在 IndexedDB,须主动创建或导入主密钥;创建后可以下载口令保护的备份。主密钥不可导出,但运行时解密后的密钥仍可能被页面脚本读取,不能抵御设备或页面上的所有攻击。真实请求受跨域限制;公开生产环境建议把密钥和模型调用放在后端。
|
|
17
|
+
|
|
18
|
+
功能开关由宿主接入时配置,不保存在用户的模型设置中。`imageGeneration`、`skills`、`quickSnippets`、`fontManagement` 默认开启;开启字体管理后,可用 `onlineFonts` 决定是否提供在线字体,关闭字体管理时不会注册字体工具,`onlineFonts` 不生效。开关不删除已有模型、规则、短语或字体配置。在线字体选项仅控制助手的字体目录和预览,不会移除宿主项目中已经使用的字体或阻止宿主自行加载字体。
|
|
19
|
+
|
|
20
|
+
工具调用轮次上限和生图累计失败上限允许设置为 `0`,表示该项无上限;无限制可能增加请求次数和费用,用户仍可停止当前对话。
|
|
21
|
+
|
|
22
|
+
## 当前边界
|
|
23
|
+
|
|
24
|
+
| 已共享 | 仍由宿主实现 |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| 助手浮窗、配置中心、历史和图片画廊、SKILL、字体和生图设置 | 本地抠图等宿主专用设置面板 |
|
|
27
|
+
| Responses 流、思考、工具轮次、原生历史、用量和图片附件 | 应用专属工具的定义、权限、确认及执行 |
|
|
28
|
+
| Kolors、Agnes、GPT Image 生图协议、图片存储和密钥管理 | 将图片或工具结果应用到宿主工作区 |
|
|
29
|
+
| 可选 `useAssistant` 通用会话控制器和浏览器加密存储 | 宿主业务操作的撤销/重做及原生文件存储 |
|
|
30
|
+
|
|
31
|
+
`useAssistant` 通过 `AssistantRunner` 接收文本、思考、工具状态和原生历史;工具可能有副作用,因此通用控制器在本轮出现工具或图片附件时禁用重新生成。需要事务回滚的应用应自行提供可验证的重做实现。演示使用 `attachment://` 资源引用保存图片历史,发送视觉请求时才加载,文本模型不读取图片;若接入方直接传入 data URL,则历史会包含该数据。
|
|
32
|
+
|
|
33
|
+
工作区读写、业务工具和原生文件权限由接入方明确实现。组件的宿主接口目前仍处于开发阶段,尚未承诺稳定的发布 API。
|
|
34
|
+
|
|
35
|
+
## 宿主接入
|
|
36
|
+
|
|
37
|
+
项目当前导出 TypeScript/TSX 源码,适合 Vite 等支持编译依赖源码的 React 构建工具;需要 React 19、React DOM 19 和 OpenAI SDK 7。浮窗和配置中心自动引入已编译并限定组件作用域的样式,宿主不需要安装 Tailwind。若修改组件中使用的工具类,组件项目维护者需运行 `bun run build:styles` 并将更新后的 `generated/sang-ai-utilities.css` 一并提交;普通接入方无需执行此命令。
|
|
38
|
+
|
|
39
|
+
同级目录本地开发时,在宿主的 `package.json` 加入:
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
"sang-ai-kit": "file:../SangAIKit"
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
然后在宿主执行 `bun install`。
|
|
46
|
+
|
|
47
|
+
本地链接存在多份 React 时,Vite 宿主需设置 `resolve.dedupe: ['react', 'react-dom']`。本地路径要求每台开发机和 CI 有相同目录结构,不能独立克隆宿主后直接安装。链接或复制行为由安装器决定,修改组件后若未更新请重新安装依赖。
|
|
48
|
+
|
|
49
|
+
`AiAssistant` 接收 `AssistantController`、浮窗控制、模型信息,以及 Markdown、设置、用量、模型控件等插槽。`AiSettings` 接收配置与校验操作,生图、SKILL、字体、抠图和密钥面板按宿主能力注入;未提供的能力不显示。`useFloatingPanel` 接收位置存储接口;`useAssistant` 和 `createResponsesSender` 提供通用会话与 Responses 适配。可直接从演示适配器开始:`demo/main.tsx` 管理配置与界面,`demo/useDemoAssistant.ts` 注册工作区、SKILL 和生图工具。
|
|
50
|
+
|
|
51
|
+
`createResponsesSender` 可选接收 `onRequest({ endpoint, body })` 观察器,在每次请求发送前报告最终 Responses URL 与 JSON body;快照不包含 HTTP headers 或 API Key。它适合诊断最终 instructions、工具 Schema 和上下文输入。生产宿主接入时应自行决定是否记录、展示或脱敏其中的用户消息与附件数据;demo 检查器会脱敏图像 Base64。
|
|
52
|
+
|
|
53
|
+
对话数据的所有权由调用方决定。使用 `useAssistant(runner, storage)` 时必须传入存储适配器;`AssistantStorage` 是通用接口,不代表组件会自动选择或创建持久化位置。宿主可接入自己的 IndexedDB、文件或服务端存储。消息上的分叉入口只有在传入 `onFork` 时显示;点击后只回调 `{ sessionId, entryId, responseItemCount? }`,不在共享组件内创建会话或复制图片。宿主负责验证标记、截断对应消息与 Responses 历史、复制引用图片并保存新会话。重新生成入口只会出现在最后一条 AI 回复上;通用控制器仅允许无工具副作用的安全重做,具有画布等外部状态的宿主应自行提供可验证的恢复能力。
|
|
54
|
+
|
|
55
|
+
图片画廊的插入操作由 `assistant.insertImage` 提供;未提供时不显示按钮。`AiAssistant` 的 `imageInsertAction` 可随宿主状态更新 `visible`、`enabled`、`label`、`successLabel` 和 `disabledReason`,`isVisible(item)` 可控制单张图片的按钮;默认不显示预览图的插入按钮。文案由宿主按当前语言提供,未配置时使用通用文案。宿主负责读取图片、决定插入位置及处理失败。默认将内置生图识别为生成图片,其余归为附件;宿主可通过 `classifyGalleryImage(image, tools)` 返回 `generated`、`preview` 或 `attachment`,返回 `undefined` 时使用默认分类。删除图片的回调由宿主负责实际清理,画廊不假设外部引用的存储方式。
|
|
56
|
+
|
|
57
|
+
宿主可通过 `createResponsesSender({ tools: [...] })` 注册函数工具;每个工具提供 JSON Schema 与 `execute`,并负责在执行前做参数校验、权限控制与必要的用户确认。工具执行状态可通过 `onTool` 回传界面,生图结果应通过会话图片存储保存,不能把付费或有副作用的工具默认当作可回滚操作。
|
|
58
|
+
|
|
59
|
+
在接入时将同一组 `features` 传给 `AiAssistant`、`AiSettings` 和 `createResponsesSender` 的 `builtIn` 参数。例如:
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
const features = {
|
|
63
|
+
imageGeneration: true,
|
|
64
|
+
skills: true,
|
|
65
|
+
quickSnippets: true,
|
|
66
|
+
fontManagement: true,
|
|
67
|
+
onlineFonts: false
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
const send = createResponsesSender({
|
|
71
|
+
baseURL, apiKey, model,
|
|
72
|
+
builtIn: { config, features, loadImage, saveImage }
|
|
73
|
+
});
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
模型配置页的“连接测试”会真实请求当前端点和模型的 Responses API,固定发送 system `this is a test` 与 user `Say OK`;请求不注册工具、不保存服务端会话,30 秒超时。模型配置为支持思考时显式发送 `reasoning.effort: none`,否则不发送 reasoning 参数。只有返回正常的非空文本才显示成功。该测试验证 Responses API 可用性,不验证图像生成端点或其他自定义工具。
|
|
77
|
+
|
|
78
|
+
生图、SKILL 和字体工具由组件库内置,发送器每轮创建独立工具实例;也可以手动调用 `createBuiltInTools({ config, features, loadImage, saveImage })`,将返回的 `tools` 与宿主业务工具合并。即使接入生图,没有已启用且有效的生图模型或缺少图片读写适配器时,也不会注册生图工具或追加生图提示词。宿主仍应提供自己的权限和确认机制。
|
|
79
|
+
|
|
80
|
+
例如,使用自己的后端代理时,可先实现会话存储和发送适配器:
|
|
81
|
+
|
|
82
|
+
```tsx
|
|
83
|
+
import { useAssistant, type AssistantRunner, type AssistantSnapshot, type AssistantStorage } from 'sang-ai-kit';
|
|
84
|
+
|
|
85
|
+
const storage: AssistantStorage = {
|
|
86
|
+
async load() {
|
|
87
|
+
const value = localStorage.getItem('my-app-ai-sessions');
|
|
88
|
+
return value ? JSON.parse(value) as AssistantSnapshot : null;
|
|
89
|
+
},
|
|
90
|
+
async save(snapshot) {
|
|
91
|
+
localStorage.setItem('my-app-ai-sessions', JSON.stringify(snapshot));
|
|
92
|
+
}
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
const runner: AssistantRunner = async (messages, events) => {
|
|
96
|
+
const response = await fetch('/api/ai', {
|
|
97
|
+
method: 'POST',
|
|
98
|
+
headers: { 'Content-Type': 'application/json' },
|
|
99
|
+
body: JSON.stringify({ messages }),
|
|
100
|
+
signal: events.signal
|
|
101
|
+
});
|
|
102
|
+
if (!response.ok) throw new Error('AI 请求失败');
|
|
103
|
+
events.onText(await response.text());
|
|
104
|
+
};
|
|
105
|
+
|
|
106
|
+
// 在 React 组件内:
|
|
107
|
+
// const assistant = useAssistant(runner, storage);
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
将 `assistant`、`useFloatingPanel` 的返回值、当前模型、文案和各插槽传给 `AiAssistant`。对接服务端 SSE、工具、图片或 Responses 原生历史时,分别调用 `events.onText`、`onTool`、`loadImage` / `saveImage` 和 `onHistory`;示例仅展示普通文本,完整用法参考演示。上例会将消息明文写入 localStorage,不适合敏感数据;图片需要另行提供 `AssistantStorage.images`,可使用 `createIndexedDbImageStore`。
|
|
111
|
+
|
|
112
|
+
思考内容与工具调用按 `responseItems` 的顺序显示。使用 `useAssistant` 和 `createResponsesSender` 的宿主无需额外调整;自定义 runner 应将思考增量传给 `events.onReasoning(text, itemId)`,并通过 `events.onHistory` 提供 Responses 原生历史。自行构造 `AssistantController` 的宿主须在每条助手消息的 `activity` 中按顺序提供 `reasoning`、`tool` 和 `text` 项,思考项格式为 `{ id, type: 'reasoning', text }`。
|
|
113
|
+
|
|
114
|
+
浮窗与配置中心通过各自的 `theme="light"`、`"dark"` 或 `"system"` 切换基础主题。宿主可在祖先元素提供 `--sang-ai-accent`;部分原有状态颜色和宿主注入面板仍未统一为主题变量。
|
|
115
|
+
|
|
116
|
+
## Git 引用
|
|
117
|
+
|
|
118
|
+
本机开发不需要 Git。若希望其他开发者或 CI 不依赖相邻目录,可在宿主安装固定提交或标签:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
bun add 'git+https://github.com/sangyuxiaowu/SangAIKit.git#<commit-or-tag>'
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## 验证
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
bun run test
|
|
128
|
+
bun run test:integration
|
|
129
|
+
bun run typecheck
|
|
130
|
+
bun run build:styles
|
|
131
|
+
bun run build
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
许可:Apache-2.0。完整条款见 [LICENSE](LICENSE)。
|