@done-coding/forge-kit-agent 0.0.0-placeholder.0 → 0.100.0-alpha.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 (105) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +54 -0
  3. package/es/_virtual/_plugin-vue_export-helper.mjs +10 -0
  4. package/es/components/bubble/AiBubbleContent.vue.mjs +7 -0
  5. package/es/components/bubble/AiBubbleContent.vue2.mjs +209 -0
  6. package/es/components/bubble/AiBubbleFooter.vue.mjs +7 -0
  7. package/es/components/bubble/AiBubbleFooter.vue2.mjs +91 -0
  8. package/es/components/bubble/AiCodeHeaderControl.vue.mjs +7 -0
  9. package/es/components/bubble/AiCodeHeaderControl.vue2.mjs +97 -0
  10. package/es/components/bubble/AiContentSplit.vue.mjs +70 -0
  11. package/es/components/bubble/AiContentSplit.vue2.mjs +4 -0
  12. package/es/components/bubble/AiPartRenderer.vue.mjs +7 -0
  13. package/es/components/bubble/AiPartRenderer.vue2.mjs +184 -0
  14. package/es/components/bubble/AiThinkBox.vue.mjs +7 -0
  15. package/es/components/bubble/AiThinkBox.vue2.mjs +155 -0
  16. package/es/components/bubble/AiTypewriter.vue.mjs +81 -0
  17. package/es/components/bubble/AiTypewriter.vue2.mjs +4 -0
  18. package/es/components/config/AiConfigProvider.vue.mjs +31 -0
  19. package/es/components/config/AiConfigProvider.vue2.mjs +4 -0
  20. package/es/components/dialogue/AiDialogue.vue.mjs +7 -0
  21. package/es/components/dialogue/AiDialogue.vue2.mjs +242 -0
  22. package/es/components/dialogue/AiDialogueGroup.vue.mjs +7 -0
  23. package/es/components/dialogue/AiDialogueGroup.vue2.mjs +133 -0
  24. package/es/components/dialogue/AiDialogueWrap.vue.mjs +7 -0
  25. package/es/components/dialogue/AiDialogueWrap.vue2.mjs +73 -0
  26. package/es/components/dialogue/AiMessageList.vue.mjs +7 -0
  27. package/es/components/dialogue/AiMessageList.vue2.mjs +111 -0
  28. package/es/components/json-trigger/LlmJsonTrigger.vue.mjs +7 -0
  29. package/es/components/json-trigger/LlmJsonTrigger.vue2.mjs +130 -0
  30. package/es/components/operation/AiOperationBar.vue.mjs +7 -0
  31. package/es/components/operation/AiOperationBar.vue2.mjs +174 -0
  32. package/es/components/operation/AiOperationBtns.vue.mjs +7 -0
  33. package/es/components/operation/AiOperationBtns.vue2.mjs +140 -0
  34. package/es/components/sender/AiSender.vue.mjs +7 -0
  35. package/es/components/sender/AiSender.vue2.mjs +74 -0
  36. package/es/components/sender/AiSenderHeader.vue.mjs +7 -0
  37. package/es/components/sender/AiSenderHeader.vue2.mjs +78 -0
  38. package/es/hooks/CodeXSlot.mjs +20 -0
  39. package/es/hooks/SessionExpose.mjs +81 -0
  40. package/es/hooks/agent-tools.mjs +95 -0
  41. package/es/hooks/agent.mjs +143 -0
  42. package/es/hooks/bubble-list.mjs +64 -0
  43. package/es/hooks/expose.mjs +133 -0
  44. package/es/hooks/fix-bubble-list-bug.mjs +65 -0
  45. package/es/hooks/sender-history.mjs +28 -0
  46. package/es/hooks/sender.mjs +197 -0
  47. package/es/hooks/session-list.mjs +154 -0
  48. package/es/hooks/sse.mjs +401 -0
  49. package/es/hooks/storage.mjs +217 -0
  50. package/es/hooks/theme.mjs +253 -0
  51. package/es/hooks/use-density.mjs +100 -0
  52. package/es/hooks/use-empty-state-center.mjs +40 -0
  53. package/es/hooks/use-keyboard-inset.mjs +87 -0
  54. package/es/index.mjs +68 -0
  55. package/es/style.css +836 -0
  56. package/es/types/index.mjs +54 -0
  57. package/es/utils/index.mjs +34 -0
  58. package/es/utils/json-from-llm.mjs +26 -0
  59. package/es/utils/request-llm.mjs +60 -0
  60. package/package.json +85 -1
  61. package/types/bridge/config-hook.d.ts +21 -0
  62. package/types/bridge/index.d.ts +69 -0
  63. package/types/bridge/plugin.d.ts +39 -0
  64. package/types/bridge/state.d.ts +26 -0
  65. package/types/bridge/storage.d.ts +10 -0
  66. package/types/components/bubble/AiBubbleContent.vue.d.ts +57 -0
  67. package/types/components/bubble/AiBubbleFooter.vue.d.ts +6 -0
  68. package/types/components/bubble/AiCodeHeaderControl.vue.d.ts +7 -0
  69. package/types/components/bubble/AiContentSplit.vue.d.ts +36 -0
  70. package/types/components/bubble/AiPartRenderer.vue.d.ts +9 -0
  71. package/types/components/bubble/AiThinkBox.vue.d.ts +31 -0
  72. package/types/components/bubble/AiTypewriter.vue.d.ts +28 -0
  73. package/types/components/config/AiConfigProvider.vue.d.ts +28 -0
  74. package/types/components/dialogue/AiDialogue.vue.d.ts +546 -0
  75. package/types/components/dialogue/AiDialogueGroup.vue.d.ts +49 -0
  76. package/types/components/dialogue/AiDialogueWrap.vue.d.ts +38 -0
  77. package/types/components/dialogue/AiMessageList.vue.d.ts +65 -0
  78. package/types/components/json-trigger/LlmJsonTrigger.vue.d.ts +43 -0
  79. package/types/components/json-trigger/types.d.ts +12 -0
  80. package/types/components/operation/AiOperationBar.vue.d.ts +36 -0
  81. package/types/components/operation/AiOperationBtns.vue.d.ts +27 -0
  82. package/types/components/sender/AiSender.vue.d.ts +38 -0
  83. package/types/components/sender/AiSenderHeader.vue.d.ts +28 -0
  84. package/types/hooks/CodeXSlot.d.ts +7 -0
  85. package/types/hooks/SessionExpose.d.ts +20 -0
  86. package/types/hooks/agent-tools.d.ts +67 -0
  87. package/types/hooks/agent.d.ts +43 -0
  88. package/types/hooks/bubble-list.d.ts +22 -0
  89. package/types/hooks/expose.d.ts +111 -0
  90. package/types/hooks/fix-bubble-list-bug.d.ts +8 -0
  91. package/types/hooks/sender-history.d.ts +41 -0
  92. package/types/hooks/sender.d.ts +101 -0
  93. package/types/hooks/session-list.d.ts +36 -0
  94. package/types/hooks/sse.d.ts +239 -0
  95. package/types/hooks/storage.d.ts +70 -0
  96. package/types/hooks/theme.d.ts +37 -0
  97. package/types/hooks/use-density.d.ts +66 -0
  98. package/types/hooks/use-empty-state-center.d.ts +23 -0
  99. package/types/hooks/use-keyboard-inset.d.ts +37 -0
  100. package/types/index.d.ts +26 -0
  101. package/types/inject/key.d.ts +20 -0
  102. package/types/types/index.d.ts +612 -0
  103. package/types/utils/index.d.ts +29 -0
  104. package/types/utils/json-from-llm.d.ts +35 -0
  105. package/types/utils/request-llm.d.ts +44 -0
@@ -0,0 +1,20 @@
1
+ import { InjectionKey } from 'vue';
2
+ import { Bridge } from '../bridge/index';
3
+ /**
4
+ * 整 bridge app 级注入 key。
5
+ * ---
6
+ * `bridge.install(app)`(即 `app.use(bridge)`)经 `app.provide(BRIDGE_KEY, bridge)`
7
+ * 把**整个 bridge 实例**注入应用级 provide 链;任意后代组件经 `inject(BRIDGE_KEY)`
8
+ * 取整 bridge(含只读响应式 `config` + `update` + `use` 等)。
9
+ * ---
10
+ * **opt-in**:仅当 app 显式 `app.use(bridge)` 时注入;未 use 则 `inject(BRIDGE_KEY)`
11
+ * 返回 `undefined`(不报错)。
12
+ * ---
13
+ * 使用 `Symbol.for` 全局注册表保证跨包 / 跨 chunk / 跨 ESM 实例的 Symbol 唯一性。
14
+ * `Symbol(key)` 每次调用产生新实例;vite chunk split 或多次模块 evaluate 可能产生
15
+ * 多个 Symbol → inject/provide 失配。
16
+ * ---
17
+ * 历史 namespace 固定,不随安装包改名或 dc-inject 生成元数据变化;
18
+ * 保持跨版本/跨 chunk 的既有 provider 与 consumer 配对。
19
+ */
20
+ export declare const BRIDGE_KEY: InjectionKey<Bridge>;
@@ -0,0 +1,612 @@
1
+ import { BubbleListItemProps } from 'vue-element-plus-x/types/BubbleList';
2
+ import { ConversationItem } from 'vue-element-plus-x/types/Conversations';
3
+ import { AiDb } from '../hooks/storage';
4
+ /** ai 聊天 用户配置 */
5
+ export type AiChatUserConfig = Pick<BubbleListItemProps, "avatar" | "avatarSize" | "avatarGap" | "avatarShape" | "avatarSrcSet" | "avatarAlt" | "avatarFit">;
6
+ /** 聊天角色枚举 */
7
+ export declare enum AiChatRoleEnum {
8
+ /** 用户 */
9
+ USER = "user",
10
+ /** ai */
11
+ AI = "ai"
12
+ }
13
+ /** 自定义的气泡列表项 */
14
+ export interface XBubbleListItemProps extends BubbleListItemProps {
15
+ /** 对话 uuid */
16
+ uuid: string;
17
+ /** 所属会话id */
18
+ sessionId: string;
19
+ /** 角色 */
20
+ role: AiChatRoleEnum;
21
+ /** 创建时间 */
22
+ createdAt: number;
23
+ /** 更新时间 */
24
+ updatedAt: number;
25
+ /** 错误信息 */
26
+ errorMsg: string;
27
+ /** 回答被中止 */
28
+ isAborted: boolean;
29
+ /** 回答结束 */
30
+ isFinished: boolean;
31
+ /** 思考时间(s) */
32
+ thinkTime: number;
33
+ /**
34
+ * @deprecated 0.3.0 起**恒为空串**,不再写入、不再渲染。
35
+ * ----
36
+ * 原为用户气泡上的「执行目标」标签,随分类学一并移除。字段保留是因为它们同时是
37
+ * `storage.ts` 的 Dexie **索引名**——改同版本号的 `stores()` 串会让下游已有库打开
38
+ * 即抛版本错误(历史对话全丢)。清理需 `.version(2)` 全量升级,留待下次真需动
39
+ * schema 时顺路做(见 docs/TECH_DEBT.md)。
40
+ */
41
+ talkGoalLabel: string;
42
+ /** @deprecated 同 `talkGoalLabel`——0.3.0 起恒为空串。 */
43
+ talkGoalValue: string;
44
+ /**
45
+ * 问题内容
46
+ * ----
47
+ * role AiChatRoleEnum.AI 才有
48
+ */
49
+ askInput?: string;
50
+ /**
51
+ * 问题对应的对话uuid
52
+ * ----
53
+ * role AiChatRoleEnum.AI 才有
54
+ */
55
+ askUuid?: string;
56
+ /**
57
+ * 展示思考内容
58
+ * ----
59
+ * role AiChatRoleEnum.AI 才有
60
+ */
61
+ showThink?: boolean;
62
+ /**
63
+ * 回复对应的对话uuid
64
+ * ----
65
+ * role AiChatRoleEnum.USER 才有
66
+ */
67
+ replyUuid?: string;
68
+ /**
69
+ * 非文本 parts(C 阶段协议去耦新增:转换器输出的 text 之外 part)。
70
+ * ----
71
+ * 文本走 `content`(markdown 流式打字机);reasoning/file/tool-call/data-* 挂此,
72
+ * 由 AiBubbleContent 在 content 之后静态渲染(流式只驱动 text)。
73
+ *
74
+ * **用户气泡同样可有**(`ask({ parts })` 写入):以用户名义发出的数据卡 / 引用卡,
75
+ * 与 AI 侧共用同一条渲染链(`#part` / `#tool` 转发口)。
76
+ */
77
+ parts?: AiMessagePart[];
78
+ /**
79
+ * parts 的正文偏移(与 `parts` 平行数组;q21yfk 方案 B 时序还原)。
80
+ * ----
81
+ * 每个 part **首次落位**时的 `content` 长度,由 sse 层记录(upsert 命中已有 id 时
82
+ * 保持首记偏移)。AiBubbleContent 据此把正文切段、parts 插回真实到达位置。
83
+ * 缺省(存量历史消息)→ 退回「正文后挂 parts」旧序渲染。
84
+ * 非 Dexie 索引字段 → 零 schema 迁移(storage.ts 注释同口径)。
85
+ */
86
+ partOffsets?: number[];
87
+ }
88
+ /** ai 聊天消息 */
89
+ export type XConversationItem = ConversationItem<{
90
+ id: string;
91
+ /** 创建时间 */
92
+ createdAt: number;
93
+ /** 更新时间 */
94
+ updatedAt: number;
95
+ /** 最后一条消息的创建时间 */
96
+ lastMsgCreatedAt: number;
97
+ /** 消息条数 */
98
+ msgCount: number;
99
+ }>;
100
+ /** ai会话基础简要信息 */
101
+ export type AiSessionBaseSimpleInfo = Pick<XConversationItem, "id">;
102
+ /**
103
+ * OpenAI 流式 `delta.tool_calls[]` 增量项(wire 原样形状)。
104
+ * ----
105
+ * 形状对齐 OpenAI Chat Completions streaming:`name` / `arguments` 嵌在 `function` 下,
106
+ * 首帧另带 `id`(= 续轮 `role:"tool"` 消息的 `tool_call_id`)。
107
+ * [MUST NOT] 拍平为顶层 `name` / `arguments`——真实端点取不到值(历史 bug,2026-08-25 修正)。
108
+ */
109
+ export interface AiOpenAIDeltaToolCall {
110
+ /** 增量锚 index(同一次调用的增量共享 index) */
111
+ index: number;
112
+ /** 工具调用 id(首帧携带;续轮 tool 消息的 tool_call_id) */
113
+ id?: string;
114
+ /** 调用类型(首帧携带,当前恒为 "function") */
115
+ type?: "function";
116
+ /** 函数增量(name 首帧携带;arguments 逐帧拼接为 JSON 字符串) */
117
+ function?: {
118
+ /** 函数名增量(首帧携带) */
119
+ name?: string;
120
+ /** 参数片段增量(逐帧拼接为 JSON 字符串) */
121
+ arguments?: string;
122
+ };
123
+ }
124
+ /** OpenAI 完整工具调用(非增量;用于续轮 assistant 消息回发)。 */
125
+ export interface AiOpenAIToolCall {
126
+ /** 工具调用 id */
127
+ id: string;
128
+ /** 调用类型 */
129
+ type: "function";
130
+ /** 函数名与完整参数(JSON 字符串) */
131
+ function: {
132
+ name: string;
133
+ arguments: string;
134
+ };
135
+ }
136
+ /**
137
+ * SSE 请求头映射(`AiSSEOptions.headers` / `AiDialogueProps.sseHeaders` 的求值结果)。
138
+ * ----
139
+ * 定义在 types 桶而非 `hooks/sse.ts`:`AiDialogueProps` 需引用它,若定义在 hooks 会形成
140
+ * types ↔ hooks 循环引用(规则 9.0 的 dts 静默漏档风险)。
141
+ */
142
+ export type AiSSEHeaders = Record<string, string>;
143
+ /**
144
+ * OpenAI Chat Completions 请求 `body.messages[]` 单条(wire 原样形状)。
145
+ * ----
146
+ * 传输层直接照发,[MUST NOT] 在此层做业务映射;`AiMessage[]` → 本形状的有损映射
147
+ * 走公开纯函数 `toOpenAIMessages`(可替换)。
148
+ */
149
+ export interface AiChatCompletionMessage {
150
+ /** 角色 */
151
+ role: "system" | "user" | "assistant" | "tool";
152
+ /** 文本内容(assistant 仅含 tool_calls 时可为 null) */
153
+ content?: string | null;
154
+ /** 具名参与者(可选) */
155
+ name?: string;
156
+ /** `role:"tool"` 必填,值 = 对应 assistant `tool_calls[].id` */
157
+ tool_call_id?: string;
158
+ /** `role:"assistant"` 时模型产出的工具调用 */
159
+ tool_calls?: AiOpenAIToolCall[];
160
+ }
161
+ /**
162
+ * 归一化 SSE 帧(转换器输入)。
163
+ * ----
164
+ * 由协议层解析 OpenAI chunk 产出:标准字段 + 原始自定义字段(`raw`)。
165
+ * 业务数据通道:content 混 markdown / 自定义 SSE 事件(raw)/ delta 扩展字段。
166
+ */
167
+ export interface AiSSEFrame {
168
+ /**
169
+ * 帧类型:message = delta 内容帧;done = 流结束([DONE] 或 finish_reason);
170
+ * error = 流中错误帧(OpenAI wire 的标准末路形态 `{"error":{...}}`)。
171
+ */
172
+ type: "message" | "done" | "error";
173
+ /** 错误帧的消息(仅 `type: "error"`)——落进气泡 `errorMsg`,[MUST NOT] 静默丢弃 */
174
+ errorMsg?: string;
175
+ /** `choices[0].delta.content` 增量文本(可能含 markdown) */
176
+ content?: string;
177
+ /**
178
+ * `choices[0].delta.reasoning_content` 增量思维链(q21yfk/ot2ihk)。
179
+ * ----
180
+ * DeepSeek 式**独立字段**投递的 thinking 痕迹;默认转换器把它映射成
181
+ * `AiReasoningPart`(`state:"streaming"`),无此字段的端点行为不变。
182
+ */
183
+ reasoningContent?: string;
184
+ /** `choices[0].delta.tool_calls` 增量(REQ-4:协议层解析预留) */
185
+ toolCalls?: AiOpenAIDeltaToolCall[];
186
+ /** `choices[0].finish_reason`(如 "stop" / "tool_calls") */
187
+ finishReason?: string | null;
188
+ /** 原始解析帧(业务自定义字段通道) */
189
+ raw?: unknown;
190
+ }
191
+ /**
192
+ * 业务转换器:帧 → 消息 parts(逐帧增量调用,支撑流式渲染)。
193
+ * ----
194
+ * 缺省恒等 `defaultSSEConverter`(content → AiTextPart);业务方注入自定义
195
+ * 转换器把自有数据映射到驱动组件的结构(AiMessagePart[])。
196
+ */
197
+ export type AiSSEConverter = (frame: AiSSEFrame) => AiMessagePart[];
198
+ /** ai 操作条 按钮集合 props */
199
+ export interface AiOperationBtnsProps {
200
+ /** 不用事件 是需要根据事件判断是否 展示关闭按钮 */
201
+ onClose?: () => void;
202
+ /**
203
+ * tooltip 位置
204
+ * ----
205
+ * bar 在left 外部设置 right
206
+ * bar 在right 外部设置 left
207
+ */
208
+ tooltipPlacement?: "left" | "right";
209
+ /** 是否折叠 */
210
+ isCollapsed?: boolean;
211
+ /** logo 图片地址(外部传入);优先级 #logo slot > logoUrl > 色块占位 */
212
+ logoUrl?: string;
213
+ }
214
+ /** ai 操作条 props */
215
+ export interface AiOperationBarProps extends Pick<AiOperationBtnsProps, "onClose" | "logoUrl"> {
216
+ /** 操作条位置 */
217
+ position?: "left" | "right";
218
+ /** 折叠时的宽度 */
219
+ collapsedWidth?: number | string;
220
+ /** 未折叠/展开的宽度 */
221
+ unCollapseWidth?: number | string;
222
+ /** 会话列表 */
223
+ list: XConversationItem[] | Readonly<XConversationItem[]>;
224
+ /** 会话列表加载更多 loading */
225
+ sessionListLoadMoreLoading?: boolean;
226
+ }
227
+ /** ai 聊天组件 props */
228
+ export interface AiDialogueProps {
229
+ /** 数据库 */
230
+ db?: AiDb;
231
+ /**
232
+ * 会话库命名空间(对齐 bridge 的 namespace 机制)。
233
+ * ----
234
+ * 派生 dexie 库名 `${namespace}/ai-db/${userName}`(不传 = `ai-db/${userName}`);
235
+ * 多应用 / 多环境隔离走 namespace,组件库不读构建期环境。
236
+ */
237
+ dbNamespace?: string;
238
+ /**
239
+ * sse url(OpenAI Chat Completions 端点)——业务端点,[MUST] 消费方显式传入。
240
+ * ----
241
+ * 无默认值(库不读宿主 env:`import.meta.env` 构建期替换会让发布包焊死包作者环境);
242
+ * 未传时发送会提示「未配置 SSE 端点」。
243
+ *
244
+ * **[SHOULD] 整个应用固定一个端点,[SHOULD NOT] 在运行期切它。** 要换模型 / 换请求
245
+ * 参数一律走 `sseBody`(`model` / `temperature` / `tool_choice` / `response_format` …,
246
+ * 每轮求值)。
247
+ * 端点是部署形态,模型与参数才是运行期该动的轴。
248
+ *
249
+ * 本项**技术上支持**运行期变更(每轮重新读取,绑 ref 即生效)——那是为了避免
250
+ * 「绑了 ref 却静默不生效」这种最坏的失败形态,不代表推荐这么用。真要跨后端切换,
251
+ * 跨端点的历史上下文混用由消费方自负,通常更该换 `key` 重开会话。
252
+ */
253
+ sseUrl?: string;
254
+ /**
255
+ * 业务转换器:SSE 帧 → 消息 parts(缺省恒等 = content → AiTextPart)。
256
+ * ----
257
+ * 协议层(OpenAI 传输)与业务数据解耦的插槽:业务自定义帧 / delta 扩展字段
258
+ * 经此映射到 AiMessagePart[](逐帧增量调用)。不做 function call 逻辑(REQ-4 仅立结构)。
259
+ */
260
+ sseConverter?: AiSSEConverter;
261
+ /**
262
+ * 附加 / 覆盖 SSE 请求头(透传 `useAiSSE`)。
263
+ * ----
264
+ * 与内置 `{ "Content-Type": "application/json" }` 浅合并,同名键由本项覆盖;
265
+ * 函数形态(可异步)每轮发起前求值一次——鉴权 token 需刷新时用它。
266
+ * 不传 = 不带 `Authorization`(组件库不持鉴权语义)。
267
+ */
268
+ sseHeaders?: AiSSEHeaders | (() => AiSSEHeaders | Promise<AiSSEHeaders>);
269
+ /**
270
+ * 附加 / 覆盖 SSE 请求 body 字段(透传 `useAiSSE`)。
271
+ * ----
272
+ * 与内置 `{ messages, stream: true }` 浅合并;**`model` 由本项提供**(0.3.0 起组件
273
+ * 不再持模型清单),`tools` / `tool_choice` / `temperature` / `response_format`
274
+ * 等亦走此口。不传 `model` 时请求体不含该键,多数网关会 400。
275
+ */
276
+ sseBody?: Record<string, unknown>;
277
+ /**
278
+ * 气泡历史 → wire `body.messages[]` 的序列化器(默认 {@link toOpenAIMessages})。
279
+ * ----
280
+ * 与 `sseConverter` 成对:那个管「帧 → parts」(入站),这个管「parts → wire」(出站)。
281
+ * 默认映射是**有损**的(`text` 拼进 content、`data-*` 序列化成文本段、`reasoning`
282
+ * 丢弃、`tool-call` / `file` 不映射);后端要的不是这个形状——典型如 data part 要走
283
+ * multimodal `content` 数组、或要挂成自定义顶层字段——就整条换掉它。
284
+ *
285
+ * 入参是**本轮全部消息**(历史 + 本轮 user,按序),返回什么就发什么。
286
+ * [MUST NOT] 在实现里改入参(与默认实现同口径:返回新数组)。
287
+ */
288
+ sseMessagesSerializer?: (messages: AiMessage[]) => AiChatCompletionMessage[];
289
+ /**
290
+ * 携带的历史消息**条数**上限(不含本轮)。
291
+ * ----
292
+ * 不传 = **全量历史**(默认,对齐业界);`<= 0` = 不带历史(单轮,等价 0.1.0 旧行为);
293
+ * `n > 0` = 只带最近 n 条。失败(`errorMsg`)与空内容气泡不入上下文。
294
+ */
295
+ historyLimit?: number;
296
+ /**
297
+ * 前端工具注册表(webAgent · 透传 `useAiAgent`)。
298
+ * ----
299
+ * 库投影成 wire `body.tools`;带 `execute` 的工具由库执行并把结果回发续轮,直到模型
300
+ * 给出终答。不传 = 不开工具循环(行为与未引入本能力时逐字节一致)。
301
+ * **与 `sseBody.tools` 二选一**——后者会整体覆盖本投影。
302
+ */
303
+ tools?: readonly AiTool[];
304
+ /**
305
+ * 工具兜底执行体:注册表里没有 `execute` 的调用交给它(与 `AiTool.execute` 同签名)。
306
+ * ----
307
+ * 需要人工确认就在这里 `await` 自己的确认 UI,否决则
308
+ * `throw new AiToolDeniedError()`(库不内置确认按钮)。
309
+ */
310
+ onToolCall?: AiToolExecutor;
311
+ /** 工具循环轮数上限(含首轮),默认 10。触顶即停且不写 errorMsg。 */
312
+ maxSteps?: number;
313
+ /** 用户名 */
314
+ userName: string;
315
+ /**
316
+ * 空态快捷问题——**点击即发送**(非填入输入框)。
317
+ * ----
318
+ * 不传 / 空数组 = 整块建议卡不渲染(只剩欢迎语)。窄容器(侧栏内嵌)自动降单列,
319
+ * 走**容器查询**而非视口媒体查询。
320
+ */
321
+ swiftAsk?: string[];
322
+ /**
323
+ * 空态欢迎语。
324
+ * ----
325
+ * 缺省按有无 `swiftAsk` 二选一:有 → `你可以这么问:`;无 → `今天有什么可以帮到你?`
326
+ */
327
+ greeting?: string;
328
+ /**
329
+ * 是否展示会话标题栏(默认 `true`)。
330
+ * ----
331
+ * 侧栏内嵌且宿主外层已有标题时传 `false`——关闭后内容区收回标题栏高度、不留空位。
332
+ */
333
+ showTitle?: boolean;
334
+ /**
335
+ * 是否按 `</think>` 标记把正文切成「思考段 + 答复段」(默认 `false`)。
336
+ * ----
337
+ * 与结构化 `reasoning` part(走 `AiPartRenderer`)是**同一件事的两条路**:仅当后端
338
+ * 把思考塞在正文文本里、且不吐 `reasoning` part 时才开,[MUST NOT] 同时依赖两条。
339
+ * 0.3.0 前此值在 `useSenderScoped` 内硬编码为 `true`、无任何开关。
340
+ */
341
+ showThink?: boolean;
342
+ /** 气泡最大宽度(默认 `"100%"`;0.3.0 前为 `"500px"`,内嵌窄容器时会溢出) */
343
+ bubbleMaxWidth?: string;
344
+ /** 展示头像 */
345
+ showAvatar?: boolean;
346
+ /** 会话标题高度(`showTitle` 为 false 时不占位) */
347
+ titleHeight?: number | string;
348
+ /** logo 图片地址(外部传入);优先级 #logo slot > logoUrl > 不渲染 */
349
+ logoUrl?: string;
350
+ }
351
+ /** ai 聊天组件组 props */
352
+ export interface AiDialogueGroupProps extends AiDialogueProps {
353
+ /** 操作条 props */
354
+ operationBarProps?: Omit<AiOperationBarProps, "list" | "sessionListLoadMoreLoading">;
355
+ }
356
+ /** ai - 打字机 props */
357
+ export interface AiTypewriterProps {
358
+ item: XBubbleListItemProps;
359
+ /** 是否可用 */
360
+ disabled?: boolean;
361
+ /** 每次增加字数 */
362
+ step?: number;
363
+ /** 间隔时间 ms */
364
+ interval?: number;
365
+ /** 后缀 */
366
+ suffix?: string;
367
+ }
368
+ /** 受控消息角色(对外):取业界 `assistant` 非内部 `ai`;含 system(AI SDK v5 同款)。 */
369
+ export type AiMessageRole = "system" | "user" | "assistant";
370
+ /** 文本 part(走 markdown 渲染)。 */
371
+ export interface AiTextPart {
372
+ type: "text";
373
+ text: string;
374
+ }
375
+ /** 推理 part(thinking 痕迹,折叠展示)。 */
376
+ export interface AiReasoningPart {
377
+ type: "reasoning";
378
+ /** 推理文本(markdown) */
379
+ text: string;
380
+ /**
381
+ * 推理流态(q21yfk):`"streaming"` = 增量中(渲染层展示「正在思考」并自动展开,
382
+ * sse 层按 D9 把后续增量**合并进同一 part** 而非逐帧追加);`"done"` / 缺省 = 已完结
383
+ * (自动折叠为「已思考(N秒)」)。业务转换器不产 state 时行为与 0.4.0 一致(逐帧追加)。
384
+ */
385
+ state?: "streaming" | "done";
386
+ /** 思考耗时(秒;流收束时由 sse 层落,缺省不展示耗时) */
387
+ thinkTime?: number;
388
+ }
389
+ /**
390
+ * 工具调用 part(function call 状态机 · AI SDK v5 方案,甲方 2026-08-02 拍板)。
391
+ * ----
392
+ * 状态机:`input-streaming` → `input-available` → `output-available` / `output-error` / `output-denied`。
393
+ * result 并入 `output`(v5 风格,不分离 tool-result);Anthropic `tool_result` 由转换器映射为
394
+ * output-available 态。本结构仅为数据契约(REQ-4),调用逻辑(webAgent)后续实现。
395
+ */
396
+ export interface AiToolPart {
397
+ type: "tool-call";
398
+ /** 增量合并锚(OpenAI delta.tool_calls 的 index / Anthropic tool_use 的 id) */
399
+ id: string;
400
+ /** 工具名 */
401
+ name: string;
402
+ /** v5 状态机 */
403
+ state: AiToolCallState;
404
+ /** 入参(增量流式中为已累积片段,input-available 后为完整 JSON) */
405
+ input?: unknown;
406
+ /** 结果(output-available 态就绪;result 并入,不分离) */
407
+ output?: unknown;
408
+ /** 错误信息(output-error 态) */
409
+ errorText?: string;
410
+ }
411
+ /**
412
+ * 工具执行上下文(`AiTool.execute` / `onToolCall` 第二参)。
413
+ * ----
414
+ * 只带**本次调用的身份信息**,[MUST NOT] 塞进消息列表 / 请求体等编排态——工具实现是
415
+ * 业务侧纯函数,越少知道循环内部越好换。
416
+ */
417
+ export interface AiToolCtx {
418
+ /** 本次调用 id(= wire `tool_calls[].id`,也是 `AiToolPart.id`) */
419
+ toolCallId: string;
420
+ /** 工具名 */
421
+ toolName: string;
422
+ /** 第几轮 LLM 请求(从 1 起) */
423
+ step: number;
424
+ /**
425
+ * 中止信号:消费方中止回答(`cancel()`)时 abort。
426
+ * ----
427
+ * 长时间挂起的 `execute`(典型:等用户填气泡里的确认表单)[SHOULD] 监听它做收尾——
428
+ * 关表单、清自己的 pending 表、reject 那条 Promise。
429
+ *
430
+ * 不监听也**不会**让库卡住:循环自身与本信号竞速,abort 即收敛为 `"cancelled"`;
431
+ * 但消费方那条 Promise 是它自己的对象,库无从 reject,故清理钩子只能是这个信号。
432
+ */
433
+ signal: AbortSignal;
434
+ }
435
+ /**
436
+ * 工具执行体(`AiTool.execute` 与 `useAiAgent` 的 `onToolCall` 同签名)。
437
+ * ----
438
+ * 两者形状刻意统一:工具名在 `ctx.toolName`,实现方 `switch` 即可,无须两套心智。
439
+ * 结果经 `Promise` 返回——「等用户点确认」这类长延迟天然由 `await` 覆盖,
440
+ * [MUST NOT] 再引 AI SDK 式 `addToolOutput` 记账回写(我们的执行点就在循环里)。
441
+ * 会挂很久的实现 [SHOULD] 监听 `ctx.signal` 做中止收尾(见 {@link AiToolCtx.signal})。
442
+ *
443
+ * 三种归宿:resolve → `output-available`;`throw new AiToolDeniedError()` →
444
+ * `output-denied`;throw 其它 → `output-error`。三者**都会**回发一条 `role:"tool"`
445
+ * 消息(OpenAI 规定每个 `tool_calls[].id` 必须有对应回复,缺一即 400)。
446
+ */
447
+ export type AiToolExecutor = (input: unknown, ctx: AiToolCtx) => unknown | Promise<unknown>;
448
+ /**
449
+ * 工具调用被拒(人工确认否决)。
450
+ * ----
451
+ * 在 `execute` / `onToolCall` 里抛出即让该调用落 `output-denied` 态,
452
+ * 并把 `message` 作为拒绝原因回发给模型(模型可据此改道,而非空等)。
453
+ * 确认 UI 本身由消费方持有——库只留状态与异步缺口(对齐 WebMCP
454
+ * `client.requestUserInteraction()` 把交互交回页面的取向)。
455
+ */
456
+ export declare class AiToolDeniedError extends Error {
457
+ constructor(message?: string);
458
+ }
459
+ /**
460
+ * 前端工具声明(形状对齐 W3C WebMCP `navigator.modelContext.registerTool`)。
461
+ * ----
462
+ * 库把注册表**投影**成 wire `body.tools`(只发 `name` / `description` / `inputSchema`,
463
+ * `execute` 不上线);模型选中后由 `useAiAgent` 回调 `execute` 并把结果回发续轮。
464
+ *
465
+ * `execute` **可选**即两种部署形态的活口:
466
+ * - 有 → 前端执行(webAgent 全链路);
467
+ * - 无 → 只投影 schema,回来的 tool_calls 不自动执行、原样渲染成 part 交消费方
468
+ * (镜像 AI SDK「省略 execute = 交客户端处理」的约定)。
469
+ *
470
+ * **安全纪律**:schema 与 `execute` 都在浏览器里、可被篡改,故前端工具只是「意图声明」,
471
+ * 权限判定与数据校验 [MUST] 永远在后端(与本仓「别编前端假守卫」同源)。
472
+ */
473
+ export interface AiTool {
474
+ /** 工具名(wire `function.name`,[MUST] 全局唯一) */
475
+ name: string;
476
+ /** 给模型看的用途说明(选型依据,[MUST NOT] 留空) */
477
+ description: string;
478
+ /** 入参 JSON Schema(与 WebMCP 同形) */
479
+ inputSchema: object;
480
+ /** 前端执行体;省略 = 只投影 schema,不自动执行 */
481
+ execute?: AiToolExecutor;
482
+ /** 行为提示(对齐 MCP annotations;库不解释语义,原样投影给模型) */
483
+ annotations?: Record<string, unknown>;
484
+ }
485
+ /**
486
+ * 工具循环的收敛原因(`useAiAgent().stopReason`)。
487
+ * ----
488
+ * - `stop`:模型给出终答(`finish_reason !== "tool_calls"`);
489
+ * - `max-steps`:轮数触顶(见 `maxSteps`),未答复的 part 停在 `input-available`;
490
+ * - `unhandled-tool-calls`:本轮有调用**无法全部答复**(缺 `execute` 且无 `onToolCall`,
491
+ * 或缺 `id` / `name`)→ 不执行任何一个、不续轮(部分答复会让下一轮 400);
492
+ * - `cancelled`:消费方中止;
493
+ * - `error`:请求 / 读流失败(错误信息落在气泡 `errorMsg`)。
494
+ */
495
+ export type AiAgentStopReason = "stop" | "max-steps" | "unhandled-tool-calls" | "cancelled" | "error";
496
+ /** 工具调用状态机(AI SDK v5)。 */
497
+ export type AiToolCallState = "input-streaming" | "input-available" | "output-available" | "output-error" | "output-denied";
498
+ /** 文件 part(图片/附件)。 */
499
+ export interface AiFilePart {
500
+ type: "file";
501
+ /** MIME 类型 */
502
+ mediaType: string;
503
+ /** 文件名(可选) */
504
+ filename?: string;
505
+ /** 文件地址(有 url 渲染图片/附件,无 url 占位) */
506
+ url?: string;
507
+ }
508
+ /**
509
+ * 业务 data part(对齐 Vercel「data parts」范式)。
510
+ * ----
511
+ * `type` [MUST] 以 `data-` 前缀;data 语义由消费方持有,平台只透传给 #part slot。
512
+ */
513
+ export interface AiDataPart {
514
+ type: `data-${string}`;
515
+ data: unknown;
516
+ }
517
+ /** 消息 part 联合(按 `type` 判别)。 */
518
+ export type AiMessagePart = AiTextPart | AiReasoningPart | AiToolPart | AiFilePart | AiDataPart;
519
+ /** 受控展示消息(对外公开类型)。 */
520
+ export interface AiMessage {
521
+ /** 消息唯一标识 */
522
+ id: string;
523
+ /** 角色 */
524
+ role: AiMessageRole;
525
+ /**
526
+ * 富内容 parts。
527
+ * ----
528
+ * 与 `content` 优先级关系:`parts` 存在则以 `parts` 为准、`content` 忽略。
529
+ */
530
+ parts?: AiMessagePart[];
531
+ /**
532
+ * 纯文本 shorthand,等价 `parts:[{type:'text',text:content}]`。
533
+ * ----
534
+ * 仅在 `parts` 缺省时生效。
535
+ */
536
+ content?: string;
537
+ }
538
+ /** 受控输入提交方式(对齐业界 Sender `submitType`)。 */
539
+ export type AiSenderSubmitType = "enter" | "shiftEnter" | "cmdOrCtrlEnter" | "altEnter";
540
+ /**
541
+ * 受控输入原语入参(对外公开类型)。
542
+ * ----
543
+ * 镜像业界 Sender 契约(Ant Design X / element-plus-x `Sender`):受控 `v-model` 值 + loading/
544
+ * disabled/placeholder/submitType + @submit,与受控 `AiMessageList` 配对成完整对话原语(规则 9/10)。
545
+ * 业务工具条(如路由选择钮)经 #header/#prefix/#action-list/#footer slot 由消费方注入,平台不持语义。
546
+ */
547
+ export interface AiSenderProps {
548
+ /** 占位提示。 */
549
+ placeholder?: string;
550
+ /** 发送中(输入禁用 + 转圈)。 */
551
+ loading?: boolean;
552
+ /** 禁用整个输入。 */
553
+ disabled?: boolean;
554
+ /** 只读(可见不可编辑)。 */
555
+ readOnly?: boolean;
556
+ /** 可一键清空。 */
557
+ clearable?: boolean;
558
+ /** 提交钮独立禁用(与 disabled 解耦,如空文本时禁发不禁输)。 */
559
+ submitBtnDisabled?: boolean;
560
+ /** 提交方式,默认 `enter`(Enter 发送)。 */
561
+ submitType?: AiSenderSubmitType;
562
+ /** 变体:`updown`(输入在上、操作区在下,默认)/ `default`。 */
563
+ variant?: "default" | "updown";
564
+ /** textarea 自适应行数。 */
565
+ autoSize?: {
566
+ minRows: number;
567
+ maxRows: number;
568
+ };
569
+ }
570
+ /**
571
+ * 归一化消息 parts(纯函数)。
572
+ * ----
573
+ * - `parts` 存在 → 以 `parts` 为准(`content` 忽略);
574
+ * - 否则 `content !== undefined` → 单 text part;
575
+ * - 皆空 → `[]`(空消息,合法但不渲染正文);
576
+ * - 相邻 text part 合并为单个(避免多 markdown 块割裂)。
577
+ *
578
+ * [MUST NOT] 修改入参(返回新数组)。
579
+ */
580
+ export declare const normalizeParts: (message: AiMessage) => AiMessagePart[];
581
+ /** `data-*` part 判别(`type` 前缀即判据,与渲染侧 `#part` 分发同口径)。 */
582
+ export declare const aiIsDataPart: (part: AiMessagePart) => part is AiDataPart;
583
+ /**
584
+ * `data-*` part → wire 文本段(纯函数 · 默认有损映射)。
585
+ * ----
586
+ * 形状 `[<type>]\n<JSON>`:带上 `type` 是因为 data part 的语义全在它上面,
587
+ * 只给一坨 JSON 模型读不出这是什么卡。不可序列化的 data(循环引用 / BigInt)
588
+ * 退回 `String(data)`,[MUST NOT] 让一张卡片炸掉整轮请求。
589
+ */
590
+ export declare const aiDataPartToWireText: (part: AiDataPart) => string;
591
+ /**
592
+ * `AiMessage[]` → OpenAI wire `messages[]`(纯函数 · 有损映射 · 可替换)。
593
+ * ----
594
+ * 传输层保持业务无关,故 parts → wire 的映射独立成可替换纯函数:消费方不满意默认
595
+ * 映射,可不用本函数、自行组装 `AiSSEOptions.messages`。
596
+ *
597
+ * **映射范围(有损,刻意)**:
598
+ * - `text` → 拼接进 `content`(经 `normalizeParts` 合并相邻 text);
599
+ * - `data-*` → 序列化成 `[<type>]\n<JSON>` 文本段并入同一条 `content`
600
+ * (见 {@link aiDataPartToWireText})——**这是「以用户名义发数据卡」进得了后续轮
601
+ * 上下文的唯一保证**:丢弃它等于该条消息映射后为空、被整条剔除;
602
+ * - `reasoning` → **丢弃**(thinking 痕迹不回发,业界通例);
603
+ * - `tool-call` / `file` → **不映射**(前者的回发由 agent 循环自持 `tool_calls` +
604
+ * `role:"tool"` 分支,后者需多模态 `content` 数组,届时另议)。
605
+ * - 多个文本段之间以空行分隔;映射后 `content` 为空串的消息**整条剔除**。
606
+ *
607
+ * 默认映射的形状不合意(如 data 要走 multimodal content 数组 / 自定义顶层字段)
608
+ * → 走 `AiDialogue` 的 `sseMessagesSerializer` 整条替换,[MUST NOT] 改本函数输出再回填。
609
+ *
610
+ * [MUST NOT] 修改入参(返回新数组),与 `normalizeParts` 同口径。
611
+ */
612
+ export declare const toOpenAIMessages: (messages: AiMessage[]) => AiChatCompletionMessage[];
@@ -0,0 +1,29 @@
1
+ /**
2
+ * 十六进制颜色转 rgba 字符串
3
+ * ---
4
+ * 等价替换原 npm 包 `hex-to-rgba`(migration-map D5:内联自有 util)。
5
+ * 支持 #RGB / #RGBA / #RRGGBB / #RRGGBBAA(带或不带 `#` 前缀)。
6
+ * @param hex 十六进制颜色
7
+ * @param alpha 透明度(0~1);未传时若 hex 自带 alpha 通道则用之,否则为 1
8
+ */
9
+ export declare const hexToRgba: (hex: string, alpha?: number) => string;
10
+ /**
11
+ * 给 CSS 数值补全单位(等价实现,宿主原件 `@/utils/cssUnit` 不可得)
12
+ * ---
13
+ * migration-map D5:等价非原件,已记 review-notes。
14
+ * - `number` 或纯数字字符串(如 `200` / `"200"`)→ 追加 `px`
15
+ * - 已含单位(`px`/`%`/`vh`/`vw`/`em`/`rem`…)或其他非纯数字字符串 → 原样返回
16
+ * - `undefined`/`null` → 原样返回
17
+ * @param value 宽高等尺寸值
18
+ */
19
+ export declare const getCssWithUnit: (value?: number | string | null) => string | undefined;
20
+ /**
21
+ * unix 时间戳格式化(等价实现,宿主原件 `@/utils` 不可得)
22
+ * ---
23
+ * migration-map D5:等价非原件,已记 review-notes。
24
+ * 自动识别秒/毫秒级时间戳(< 1e12 视为秒级,乘以 1000)。
25
+ * 支持 token:`YYYY` `MM` `DD` `HH` `mm` `ss`。
26
+ * @param ts unix 时间戳(秒或毫秒)
27
+ * @param format 输出格式,默认 `YYYY-MM-DD HH:mm:ss`
28
+ */
29
+ export declare const formatTimestamp: (ts: number, format?: string) => string;