sang-ai-kit 0.0.0-stage → 0.2.0

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.
Files changed (69) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +135 -3
  3. package/generated/sang-ai-utilities.css +4591 -0
  4. package/package.json +81 -5
  5. package/src/AiAssistant.tsx +953 -0
  6. package/src/AiChat.tsx +82 -0
  7. package/src/AiSettings.tsx +1441 -0
  8. package/src/ChatScrollbar.tsx +116 -0
  9. package/src/EncryptionKeySettings.tsx +568 -0
  10. package/src/FontSettings.tsx +507 -0
  11. package/src/ImageModelSettings.tsx +627 -0
  12. package/src/ModelControls.tsx +238 -0
  13. package/src/SessionList.tsx +1180 -0
  14. package/src/SkillSettings.tsx +726 -0
  15. package/src/TokenUsageBar.tsx +413 -0
  16. package/src/ToolDuration.tsx +31 -0
  17. package/src/assistant.css +2126 -0
  18. package/src/assistantTypes.ts +144 -0
  19. package/src/background-removal/BackgroundRemovalSettings.tsx +502 -0
  20. package/src/background-removal/ColorMattingEditor.tsx +649 -0
  21. package/src/background-removal/background-removal.css +294 -0
  22. package/src/background-removal/color-matting.css +838 -0
  23. package/src/background-removal/colorMatting.ts +117 -0
  24. package/src/background-removal/colorMatting.worker.ts +21 -0
  25. package/src/background-removal/index.ts +92 -0
  26. package/src/background-removal/inference.worker.ts +117 -0
  27. package/src/background-removal/models.ts +65 -0
  28. package/src/background-removal/processing.ts +61 -0
  29. package/src/background-removal/resources.ts +114 -0
  30. package/src/background-removal/status.ts +23 -0
  31. package/src/background-removal/storage.ts +56 -0
  32. package/src/background-removal/tool.ts +70 -0
  33. package/src/background-removal/types.ts +38 -0
  34. package/src/background-removal/useResources.ts +38 -0
  35. package/src/browserAiStore.ts +44 -0
  36. package/src/builtInToolDefinitions.ts +68 -0
  37. package/src/builtInTools.ts +120 -0
  38. package/src/bun-env.d.ts +25 -0
  39. package/src/configStore.ts +287 -0
  40. package/src/conversationUtils.ts +146 -0
  41. package/src/encryption.ts +51 -0
  42. package/src/endpointConnection.ts +37 -0
  43. package/src/features.ts +29 -0
  44. package/src/floatingGeometry.ts +16 -0
  45. package/src/fonts.ts +101 -0
  46. package/src/id.ts +4 -0
  47. package/src/image-generation/adapters/agnes.ts +24 -0
  48. package/src/image-generation/adapters/gptImage.ts +38 -0
  49. package/src/image-generation/adapters/kolors.ts +20 -0
  50. package/src/image-generation/index.ts +87 -0
  51. package/src/image-generation/models.ts +51 -0
  52. package/src/image-generation/results.ts +53 -0
  53. package/src/image-generation/types.ts +56 -0
  54. package/src/imageAttachments.ts +70 -0
  55. package/src/imageStore.ts +59 -0
  56. package/src/imageToolHost.ts +86 -0
  57. package/src/index.ts +52 -0
  58. package/src/modelConfig.ts +110 -0
  59. package/src/openai.ts +185 -0
  60. package/src/responses.ts +27 -0
  61. package/src/sessionTypes.ts +25 -0
  62. package/src/settingsTypes.ts +56 -0
  63. package/src/skills.ts +40 -0
  64. package/src/style.css +112 -0
  65. package/src/toolLoop.ts +50 -0
  66. package/src/useAssistant.ts +296 -0
  67. package/src/useChatScroll.ts +113 -0
  68. package/src/useFloatingPanel.ts +71 -0
  69. package/src/useResolvedTheme.ts +17 -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,135 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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`、`backgroundRemoval` 默认开启;开启字体管理后,可用 `onlineFonts` 决定是否提供在线字体,关闭字体管理时不会注册字体工具,`onlineFonts` 不生效。开关不删除已有模型、规则、短语或字体配置。在线字体选项仅控制助手的字体目录和预览,不会移除宿主项目中已经使用的字体或阻止宿主自行加载字体。抠图无需内置模型,颜色抠图直接可用;智能模型需在线下载,详见 [本地抠图](docs/background-removal.md)。
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、设置、用量、模型控件等插槽;界面不要求宿主暴露 API Key,发送或鉴权失败由宿主报告。`createResponsesSender` 和连接测试在 Key 为空时不发送 `Authorization`,适用于本地服务或代理;服务是否允许无凭据请求由服务端决定。`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`,并负责在执行前做参数校验、权限控制与必要的用户确认。普通结果保持 JSON 文本;需要让模型查看文档页面预览或其他图片时,可返回 `ResponsesToolContent`,详见 [多模态工具结果](docs/03-features-and-tools.md#多模态工具结果)。工具执行状态可通过 `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
+ backgroundRemoval: true
69
+ };
70
+
71
+ const send = createResponsesSender({
72
+ baseURL, apiKey, model,
73
+ builtIn: { config, features, loadImage, saveImage }
74
+ });
75
+ ```
76
+
77
+ 模型配置页的“连接测试”会真实请求当前端点和模型的 Responses API,固定发送 system `this is a test` 与 user `Say OK`;请求不注册工具、不保存服务端会话,30 秒超时。测试使用模型当前的思考开关和强度,不支持思考时不发送思考参数;关闭 Agnes 思考时使用 `chat_template_kwargs.enable_thinking: false`,其他模型使用 `reasoning.effort: none`。只有返回正常的非空文本才显示成功。该测试验证 Responses API 可用性,不验证图像生成端点或其他自定义工具。
78
+
79
+ 生图、SKILL、字体和抠图工具由组件库内置,发送器每轮创建独立工具实例;也可以手动调用 `createBuiltInTools({ config, features, loadImage, saveImage })`,将返回的 `tools` 与宿主业务工具合并。图片工具可使用会话读写适配器或宿主扩展,不要与同名宿主工具重复注册。没有已启用且有效的生图模型,或既没有图片读写适配器也没有生图宿主扩展时,不会注册生图工具或追加生图提示词。宿主仍应提供自己的权限和确认机制,详见[内置工具链](docs/03-features-and-tools.md#内置工具链-createbuiltintools)。
80
+
81
+ 例如,使用自己的后端代理时,可先实现会话存储和发送适配器:
82
+
83
+ ```tsx
84
+ import { useAssistant, type AssistantRunner, type AssistantSnapshot, type AssistantStorage } from 'sang-ai-kit';
85
+
86
+ const storage: AssistantStorage = {
87
+ async load() {
88
+ const value = localStorage.getItem('my-app-ai-sessions');
89
+ return value ? JSON.parse(value) as AssistantSnapshot : null;
90
+ },
91
+ async save(snapshot) {
92
+ localStorage.setItem('my-app-ai-sessions', JSON.stringify(snapshot));
93
+ }
94
+ };
95
+
96
+ const runner: AssistantRunner = async (messages, events) => {
97
+ const response = await fetch('/api/ai', {
98
+ method: 'POST',
99
+ headers: { 'Content-Type': 'application/json' },
100
+ body: JSON.stringify({ messages }),
101
+ signal: events.signal
102
+ });
103
+ if (!response.ok) throw new Error('AI 请求失败');
104
+ events.onText(await response.text());
105
+ };
106
+
107
+ // 在 React 组件内:
108
+ // const assistant = useAssistant(runner, storage);
109
+ ```
110
+
111
+ 将 `assistant`、`useFloatingPanel` 的返回值、当前模型、文案和各插槽传给 `AiAssistant`。对接服务端 SSE、工具、图片或 Responses 原生历史时,分别调用 `events.onText`、`onTool`、`loadImage` / `saveImage` 和 `onHistory`;示例仅展示普通文本,完整用法参考演示。上例会将消息明文写入 localStorage,不适合敏感数据;图片需要另行提供 `AssistantStorage.images`,可使用 `createIndexedDbImageStore`。
112
+
113
+ 思考内容与工具调用按 `responseItems` 的顺序显示。使用 `useAssistant` 和 `createResponsesSender` 的宿主无需额外调整;自定义 runner 应将思考增量传给 `events.onReasoning(text, itemId)`,并通过 `events.onHistory` 提供 Responses 原生历史。自行构造 `AssistantController` 的宿主须在每条助手消息的 `activity` 中按顺序提供 `reasoning`、`tool` 和 `text` 项,思考项格式为 `{ id, type: 'reasoning', text }`。
114
+
115
+ 浮窗与配置中心通过各自的 `theme="light"`、`"dark"` 或 `"system"` 切换基础主题。宿主可在祖先元素提供 `--sang-ai-accent`;部分原有状态颜色和宿主注入面板仍未统一为主题变量。
116
+
117
+ ## Git 引用
118
+
119
+ 本机开发不需要 Git。若希望其他开发者或 CI 不依赖相邻目录,可在宿主安装固定提交或标签:
120
+
121
+ ```bash
122
+ bun add 'git+https://github.com/sangyuxiaowu/SangAIKit.git#<commit-or-tag>'
123
+ ```
124
+
125
+ ## 验证
126
+
127
+ ```bash
128
+ bun run test
129
+ bun run test:integration
130
+ bun run typecheck
131
+ bun run build:styles
132
+ bun run build
133
+ ```
134
+
135
+ 许可:Apache-2.0。完整条款见 [LICENSE](LICENSE)。