@pactor-app/chat 1.15.6 → 1.16.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 (7) hide show
  1. package/README.md +7 -3
  2. package/dist/index.cjs +490 -22
  3. package/dist/index.d.cts +147 -37
  4. package/dist/index.d.ts +147 -37
  5. package/dist/index.js +481 -22
  6. package/package.json +6 -6
  7. package/styles.css +169 -8
package/dist/index.d.cts CHANGED
@@ -9,7 +9,9 @@ import { RefObject, ReactNode, ComponentType } from 'react';
9
9
  *
10
10
  * 零 React，可纯 Node 测试；状态语义与 ConversationStore 同模式
11
11
  * （不可变更新 + subscribe 通知，兼容 useSyncExternalStore）。
12
- * store 只持当前一个产出物：多产出物 / 历史由业务层自行管理后注入。
12
+ * store 持会话内全部产出物列表 + 当前激活项：open 按 id upsert 并
13
+ * 激活；面板 tabs / 目录列表视图经 list() 读取；close 只关闭面板
14
+ * （清空激活项），列表保留供重开时继续切换。
13
15
  */
14
16
  /** 产出物：dsl kind 的 content 为 DslNode 普通对象，其余 kind 为字符串 */
15
17
  interface ChatArtifact {
@@ -19,25 +21,66 @@ interface ChatArtifact {
19
21
  content: string | DslNode;
20
22
  /** code kind 的语言标记（仅作角标展示） */
21
23
  language?: string;
24
+ /**
25
+ * 文件类型（扩展名，大小写 / 带点均可，如 'png' / '.MD'）：
26
+ * 图片类扩展名走内建图片预览（content 为 URL / data URL，
27
+ * svg 另支持原始标记）；自定义查看器（artifactViewers）按此键匹配。
28
+ * 缺省从 title 的扩展名推导
29
+ */
30
+ fileType?: string;
22
31
  meta?: Record<string, unknown>;
23
32
  }
33
+ /** 内建图片预览的扩展名（小写不带点） */
34
+ declare const ARTIFACT_IMAGE_EXTENSIONS: readonly string[];
35
+ /** 解析产物文件类型：显式 fileType 优先，缺省取 title 扩展名；均无返回 null */
36
+ declare function resolveArtifactFileType(artifact: ChatArtifact): string | null;
37
+ /** 是否图片类产物（扩展名命中内建图片集合） */
38
+ declare function isImageArtifact(artifact: ChatArtifact): boolean;
24
39
  /** update 的补丁：id 不可改 */
25
40
  type ArtifactPatch = Partial<Omit<ChatArtifact, 'id'>>;
41
+ /** 消息形态的最小契约（与 model.ts ChatMessage 结构化兼容，保持本文件零依赖） */
42
+ interface ArtifactPartCarrier {
43
+ parts: Array<{
44
+ type: string;
45
+ artifact?: ChatArtifact;
46
+ status?: string;
47
+ }>;
48
+ }
49
+ /**
50
+ * 从会话消息流归集产出物（tabs / 目录列表视图的默认数据源）：
51
+ * 按消息序遍历 artifact part，同 id 后者覆盖（流式更新取最新），
52
+ * 顺序保持首次出现序；streaming 中的 part 跳过（就绪后再入列）。
53
+ * 纯函数，输入消息数组引用不变时结果可经 useMemo 缓存。
54
+ */
55
+ declare function collectArtifacts(messages: readonly ArtifactPartCarrier[]): ChatArtifact[];
26
56
  /**
27
- * ArtifactStore（设计决策 D1）：当前产出物的可变容器。
57
+ * 合并消息流归集与 store 打开记录：stream 顺序为主，冲突 id 取
58
+ * store 版本（store.update 的流式补丁可能领先消息 part），
59
+ * store 中未入流的产物（宿主直接 open 的）追加在后。
60
+ */
61
+ declare function mergeArtifacts(stream: readonly ChatArtifact[], opened: readonly ChatArtifact[]): ChatArtifact[];
62
+ /**
63
+ * ArtifactStore（设计决策 D1）：产出物列表的可变容器。
28
64
  * 可注入（services.artifactStore）或由组合层自持（ref 保持）。
29
65
  * 对未 open 状态下的 update 宽容：console.warn 并忽略，不抛错。
66
+ * list() 返回的内部数组不可变、引用在不变时保持稳定
67
+ * （useSyncExternalStore 快照安全）。
30
68
  */
31
69
  declare class ArtifactStore {
32
- private artifact;
70
+ private artifacts;
71
+ private activeId;
33
72
  private readonly listeners;
34
- /** 当前产出物（未打开时为 null；引用在不变时保持稳定） */
73
+ /** 当前激活产出物（未打开时为 null；引用在不变时保持稳定） */
35
74
  get(): ChatArtifact | null;
36
- /** 打开（或替换）当前产出物 */
75
+ /** 全部产出物（插入序；数组不可变，引用稳定） */
76
+ list(): ChatArtifact[];
77
+ /** 打开（或按 id 替换）产出物并激活 */
37
78
  open(artifact: ChatArtifact): void;
38
- /** 部分更新当前产出物（id 不可改）；未 open 时告警并忽略 */
79
+ /** 切换激活项（未知 id 告警并忽略，不抛错） */
80
+ activate(id: string): void;
81
+ /** 部分更新当前激活产出物（id 不可改）；未 open 时告警并忽略 */
39
82
  update(patch: ArtifactPatch): void;
40
- /** 关闭面板（未打开时幂等，不重复通知） */
83
+ /** 关闭面板：清空激活项，列表保留（未打开时幂等，不重复通知） */
41
84
  close(): void;
42
85
  /** 订阅变更；返回退订函数 */
43
86
  subscribe(listener: () => void): () => void;
@@ -261,6 +304,21 @@ declare class ConversationStore {
261
304
  private commit;
262
305
  }
263
306
 
307
+ /** 下载文件名：title 已带扩展名原样使用；否则补 fileType / kind 缺省扩展名 */
308
+ declare function resolveArtifactFilename(artifact: ChatArtifact): string;
309
+ /**
310
+ * 构建下载 Blob；图片内容为 http(s) URL 时返回 null（由 downloadArtifact
311
+ * 走 fetch 取回，失败降级新标签打开）
312
+ */
313
+ declare function buildArtifactBlob(artifact: ChatArtifact): Blob | null;
314
+ /** 触发浏览器下载（Object URL + 临时锚点） */
315
+ declare function saveBlob(blob: Blob, filename: string): void;
316
+ /**
317
+ * 下载产物：文本类 / dsl JSON / 图片 data URL 与 svg 标记直接存 Blob；
318
+ * 图片 http(s) URL fetch 取回（跨域失败降级新标签打开）
319
+ */
320
+ declare function downloadArtifact(artifact: ChatArtifact): Promise<void>;
321
+
264
322
  /**
265
323
  * Streaming 事件模型与 reducer（设计决策 D2，设计文档第 69 节）。
266
324
  *
@@ -653,6 +711,69 @@ interface UseChatAutoScrollResult {
653
711
  }
654
712
  declare function useChatAutoScroll({ messageCount, lastContentLength, isStreaming, }: UseChatAutoScrollOptions): UseChatAutoScrollResult;
655
713
 
714
+ /**
715
+ * ArtifactPanel（spec: chat-artifact-panel，设计决策 D2/D3）：
716
+ * 产出物预览面板 = 标题栏（标题 + kind 角标 + 关闭按钮）+ 内容区。
717
+ *
718
+ * 内容按 artifact.kind 分发内建渲染器：markdown 经 @pactor-app/markdown
719
+ * 安全渲染；code 只读代码块（language 仅作角标，不引高亮依赖）；
720
+ * text 预格式文本；dsl 经 guardChatDsl 白名单守卫 + renderChildren
721
+ * 活预览（与消息流 dsl part 同安全级），被拦截 / 渲染失败一律降级为
722
+ * 受控占位块（ChatDenied 同款），MUST NOT 抛错。
723
+ *
724
+ * 纯展示组件：关闭只触发 onClose，不单方面修改外部状态。
725
+ */
726
+ interface ArtifactPanelProps {
727
+ /** 当前产出物；null 时内容区为空态（inspector 槽场景常见） */
728
+ artifact?: ChatArtifact | null;
729
+ /**
730
+ * 会话内全部产出物（多产物场景）：提供后 header 左端展示目录列表
731
+ * 切换钮；多于 1 个时 header 下沿展示 tab 条（kind 图标 + 名称）
732
+ */
733
+ artifacts?: ChatArtifact[];
734
+ /** 当前激活产出物 id（tabs 高亮；缺省取 artifact.id） */
735
+ activeArtifactId?: string;
736
+ /** tab / 目录列表点击切换回调（受控切换，面板不自改外部状态） */
737
+ onSelectArtifact?: (artifact: ChatArtifact) => void;
738
+ /** 面板内容槽：提供时整体替代内建渲染器（标题栏保留） */
739
+ inspector?: ReactNode;
740
+ /** 关闭按钮 / 遮罩点击回调 */
741
+ onClose?: () => void;
742
+ /** dsl 产出物活预览的 Safe Registry；缺省时 dsl 内容渲染降级块 */
743
+ safeRegistry?: Registry<unknown>;
744
+ /** 注入 dsl 预览作用域 user */
745
+ user?: Record<string, unknown>;
746
+ /**
747
+ * 自定义产物查看器（spec: chat-artifact-panel / 自定义预览）：
748
+ * 按扩展名 / kind 对特定文件格式提供自定义预览，优先于内建渲染器
749
+ */
750
+ artifactViewers?: ArtifactViewers;
751
+ className?: string;
752
+ }
753
+ /**
754
+ * 产物目录树（纯函数）：按 id 的 '/' 分段建目录层级——
755
+ * id 形如 `reports/q3/月报` 时产出 reports → q3 两级目录；
756
+ * 无 '/' 分段的产物平铺在根层。目录先于文件、各自按名称排序。
757
+ */
758
+ interface ArtifactTreeNode {
759
+ /** 段名（目录名或产物标题） */
760
+ name: string;
761
+ /** 完整路径（目录为 id 前缀，文件为产物 id） */
762
+ path: string;
763
+ artifact?: ChatArtifact;
764
+ children: ArtifactTreeNode[];
765
+ }
766
+ declare function buildArtifactTree(artifacts: ChatArtifact[]): ArtifactTreeNode[];
767
+ /**
768
+ * 自定义产物查看器（spec: chat-artifact-panel / 自定义预览）：
769
+ * 键为扩展名（小写不带点，如 'png' / 'md'）或 kind
770
+ * （'markdown' / 'code' / 'text' / 'dsl'）；扩展名键优先于 kind 键，
771
+ * 均优先于内建渲染器。查看器抛错不经守卫——宿主代码自负。
772
+ */
773
+ type ArtifactViewer = (artifact: ChatArtifact) => ReactNode;
774
+ type ArtifactViewers = Record<string, ArtifactViewer>;
775
+ declare function ArtifactPanel({ artifact, artifacts, activeArtifactId, onSelectArtifact, inspector, onClose, safeRegistry, user, artifactViewers, className, }: ArtifactPanelProps): ReactNode;
776
+
656
777
  /**
657
778
  * EmptyState（spec: chat-empty-state，设计决策 D0/D1）：空会话欢迎页。
658
779
  *
@@ -716,6 +837,12 @@ interface ChatWorkspaceServices {
716
837
  storeFactory?: () => ConversationStore;
717
838
  /** 产出物面板 store（spec: chat-artifact-panel）；缺省包内默认构造 */
718
839
  artifactStore?: ArtifactStore;
840
+ /**
841
+ * 自定义产物查看器（spec: chat-artifact-panel / 自定义预览）：
842
+ * 按键（扩展名小写不带点，或 kind）对特定文件格式提供自定义预览，
843
+ * 优先于内建渲染器；函数不进 DSL props，统一经服务注入
844
+ */
845
+ artifactViewers?: ArtifactViewers;
719
846
  /** Safe Registry（createSafeRegistry 包装后的白名单注册表） */
720
847
  safeRegistry?: Registry<unknown>;
721
848
  /** capability 白名单与确认链 */
@@ -805,6 +932,12 @@ interface ChatWorkspaceProps {
805
932
  onArtifact?: (artifact: ChatArtifact) => void;
806
933
  /** 产出物卡片"在面板中打开"回调（runtime 绑定 events.onOpenArtifact 时传入） */
807
934
  onOpenArtifact?: (artifact: ChatArtifact) => void;
935
+ /**
936
+ * 面板 tab / 目录列表点击切换回调（runtime 绑定 events.onSelectArtifact
937
+ * 时传入；受控典型接法：setState artifact=${event.artifact}）。
938
+ * 多产物列表缺省由组合层从消息流归集，无需显式注入
939
+ */
940
+ onSelectArtifact?: (artifact: ChatArtifact) => void;
808
941
  /**
809
942
  * 内建 header 操作组（spec: chat-dsl-component / Header 配置，决策 D4）：
810
943
  * 按数组顺序渲染（headerExtra 槽之前）；缺省不渲染
@@ -981,6 +1114,8 @@ interface ChatProps {
981
1114
  onArtifact?: (artifact: ChatArtifact) => void;
982
1115
  /** 产出物卡片"在面板中打开"按钮点击回调（event 作用域含 artifact；受控场景的开面板入口） */
983
1116
  onOpenArtifact?: (artifact: ChatArtifact) => void;
1117
+ /** 面板 tab / 目录列表点击切换回调（event 作用域含 artifact；受控典型接法：setState artifact=${event.artifact}） */
1118
+ onSelectArtifact?: (artifact: ChatArtifact) => void;
984
1119
  className?: string;
985
1120
  /** 发送回调：与 transport 驱动 turn 并行（同 ChatView onSend 语义） */
986
1121
  onSend?: (text: string) => void;
@@ -1010,7 +1145,7 @@ declare function ChatSidebarMenu({ menu, activeMenuKey, onMenuSelect, }: {
1010
1145
  * 「未配置聊天服务」提示并 console.warn，不抛错。组合逻辑与
1011
1146
  * createChatWorkspace 共用内部 ChatComposition（决策 D5）。
1012
1147
  */
1013
- declare function Chat({ title, greeting, subtitle, suggestions, conversationId, params, showHeader, menu, activeMenuKey, sidebar, toolbarStart, toolbarEnd, composerFooter, composerBottom, hideToolbar, headerExtra, header, headerActions, editableTitle, onExport, onThemeChange, onClear, onTitleChange, models, model, onModelChange, modelPlacement, contexts, onContextsChange, messageActions, onMessageAction, artifact, panelOpen, onPanelClose, inspector, onArtifact, onOpenArtifact, className, onSend, onMenuSelect, }: ChatProps): ReactNode;
1148
+ declare function Chat({ title, greeting, subtitle, suggestions, conversationId, params, showHeader, menu, activeMenuKey, sidebar, toolbarStart, toolbarEnd, composerFooter, composerBottom, hideToolbar, headerExtra, header, headerActions, editableTitle, onExport, onThemeChange, onClear, onTitleChange, models, model, onModelChange, modelPlacement, contexts, onContextsChange, messageActions, onMessageAction, artifact, panelOpen, onPanelClose, inspector, onArtifact, onOpenArtifact, onSelectArtifact, className, onSend, onMenuSelect, }: ChatProps): ReactNode;
1014
1149
  /** Chat 的 DSL 组件类型名 */
1015
1150
  declare const CHAT_COMPONENT_TYPE = "Chat";
1016
1151
  /**
@@ -1073,33 +1208,6 @@ declare const CHAT_SHELL_COMPONENT_TYPE = "ChatShell";
1073
1208
  */
1074
1209
  declare function registerChatShellComponent(registry: Registry<unknown>): void;
1075
1210
 
1076
- /**
1077
- * ArtifactPanel（spec: chat-artifact-panel，设计决策 D2/D3）：
1078
- * 产出物预览面板 = 标题栏（标题 + kind 角标 + 关闭按钮）+ 内容区。
1079
- *
1080
- * 内容按 artifact.kind 分发内建渲染器：markdown 经 @pactor-app/markdown
1081
- * 安全渲染；code 只读代码块（language 仅作角标，不引高亮依赖）；
1082
- * text 预格式文本；dsl 经 guardChatDsl 白名单守卫 + renderChildren
1083
- * 活预览（与消息流 dsl part 同安全级），被拦截 / 渲染失败一律降级为
1084
- * 受控占位块（ChatDenied 同款），MUST NOT 抛错。
1085
- *
1086
- * 纯展示组件：关闭只触发 onClose，不单方面修改外部状态。
1087
- */
1088
- interface ArtifactPanelProps {
1089
- /** 当前产出物；null 时内容区为空态（inspector 槽场景常见） */
1090
- artifact?: ChatArtifact | null;
1091
- /** 面板内容槽：提供时整体替代内建渲染器（标题栏保留） */
1092
- inspector?: ReactNode;
1093
- /** 关闭按钮 / 遮罩点击回调 */
1094
- onClose?: () => void;
1095
- /** dsl 产出物活预览的 Safe Registry；缺省时 dsl 内容渲染降级块 */
1096
- safeRegistry?: Registry<unknown>;
1097
- /** 注入 dsl 预览作用域 user */
1098
- user?: Record<string, unknown>;
1099
- className?: string;
1100
- }
1101
- declare function ArtifactPanel({ artifact, inspector, onClose, safeRegistry, user, className, }: ArtifactPanelProps): ReactNode;
1102
-
1103
1211
  /**
1104
1212
  * 侧栏抽屉 context（spec: chat-app-shell）：侧栏内容（如导航项）在导航后
1105
1213
  * 调用 `close()` 关闭移动端抽屉；不在 AppShell 内时返回 null，
@@ -1346,7 +1454,9 @@ declare function ChatView({ store, transport, onSend, safeRegistry, capabilities
1346
1454
  * 答案阶段自动折叠，用户操作后 pin。
1347
1455
  *
1348
1456
  * 折叠状态机（每条消息独立，随组件实例记忆）：`auto | pinned-open |
1349
- * pinned-closed`——auto 跟随流式阶段；用户点击后 pin，不再自动变更。
1457
+ * pinned-closed`——auto 跟随流式阶段但带单向闩锁（自动折叠一次后
1458
+ * 不再自动展开，防止 mode 回跳引起展开/折叠闪烁）；用户点击后 pin，
1459
+ * 不再自动变更。
1350
1460
  */
1351
1461
  interface ActivityTraceProps {
1352
1462
  message: ChatMessage;
@@ -1493,4 +1603,4 @@ interface ChatLayoutRegistry {
1493
1603
  /** 注册 chat 布局（已注册时不覆盖，与 createLayoutRegistry 约定一致） */
1494
1604
  declare function registerChatLayout(layoutRegistry: ChatLayoutRegistry): void;
1495
1605
 
1496
- export { ActivityTrace, type ActivityTraceProps, AppShell, type AppShellProps, ArtifactPanel, type ArtifactPanelProps, type ArtifactPatch, ArtifactStore, type BuiltinMessageAction, CHAT_COMPONENT_TYPE, CHAT_DENIED_TYPE, CHAT_LAYOUT_TYPE, CHAT_SHELL_COMPONENT_TYPE, type CapabilityActionDeps, type CapabilityHandler, Chat, type ChatArtifact, type ChatAttachment, type ChatCapabilityRegistry, type ChatConfirm, type ChatConfirmRequest, type ChatContextItem, type ChatContextSource, ChatDenied, type ChatEvent, type ChatHeaderAction, type ChatInput, ChatLayout, type ChatLayoutProps, type ChatLayoutRegistry, type ChatMenuItem, type ChatMessage, type ChatMessageAction, type ChatModelOption, type ChatPart, type ChatPermissionChecker, type ChatProps, type ChatRole, type ChatRuntime, type ChatScope, type ChatServices, ChatServicesProvider, ChatShell, type ChatShellProps, ChatSidebarMenu, type ChatSuggestion, type ChatTransport, type ChatTurnResult, ChatView, type ChatViewProps, type ChatWorkspaceProps, type ChatWorkspaceServices, Composer, type ComposerProps, ConversationStore, type CreateChatRuntimeOptions, DEFAULT_CHAT_GREETING, EmptyState, type EmptyStateProps, type ManualChatDriver, MessageActions, type MessageActionsProps, MessageBubble, type MessageBubbleProps, type MessagePatch, type MessageStatus, type PartPatch, type PartRef, PartRenderer, type PartRendererProps, type PartStatus, type RunChatTurnOptions, type StreamingMode, type ToolCallStatus, type ToolTraceEntry, type UseChatAutoScrollOptions, type UseChatAutoScrollResult, type UseSmoothStreamTextOptions, applyChatEvent, buildChatScope, collectMessageText, createChatComponentRegistry, createChatId, createChatRuntime, createChatWorkspace, createManualDriver, createSafeRegistry, detectStreamingMode, guardChatDsl, pairToolTraces, registerCapabilityAction, registerChatComponent, registerChatLayout, registerChatShellComponent, runChatTurn, runRegenerateTurn, useChatAutoScroll, useChatServices, useSidebarDrawer, useSmoothStreamText };
1606
+ export { ARTIFACT_IMAGE_EXTENSIONS, ActivityTrace, type ActivityTraceProps, AppShell, type AppShellProps, ArtifactPanel, type ArtifactPanelProps, type ArtifactPatch, ArtifactStore, type ArtifactTreeNode, type ArtifactViewer, type ArtifactViewers, type BuiltinMessageAction, CHAT_COMPONENT_TYPE, CHAT_DENIED_TYPE, CHAT_LAYOUT_TYPE, CHAT_SHELL_COMPONENT_TYPE, type CapabilityActionDeps, type CapabilityHandler, Chat, type ChatArtifact, type ChatAttachment, type ChatCapabilityRegistry, type ChatConfirm, type ChatConfirmRequest, type ChatContextItem, type ChatContextSource, ChatDenied, type ChatEvent, type ChatHeaderAction, type ChatInput, ChatLayout, type ChatLayoutProps, type ChatLayoutRegistry, type ChatMenuItem, type ChatMessage, type ChatMessageAction, type ChatModelOption, type ChatPart, type ChatPermissionChecker, type ChatProps, type ChatRole, type ChatRuntime, type ChatScope, type ChatServices, ChatServicesProvider, ChatShell, type ChatShellProps, ChatSidebarMenu, type ChatSuggestion, type ChatTransport, type ChatTurnResult, ChatView, type ChatViewProps, type ChatWorkspaceProps, type ChatWorkspaceServices, Composer, type ComposerProps, ConversationStore, type CreateChatRuntimeOptions, DEFAULT_CHAT_GREETING, EmptyState, type EmptyStateProps, type ManualChatDriver, MessageActions, type MessageActionsProps, MessageBubble, type MessageBubbleProps, type MessagePatch, type MessageStatus, type PartPatch, type PartRef, PartRenderer, type PartRendererProps, type PartStatus, type RunChatTurnOptions, type StreamingMode, type ToolCallStatus, type ToolTraceEntry, type UseChatAutoScrollOptions, type UseChatAutoScrollResult, type UseSmoothStreamTextOptions, applyChatEvent, buildArtifactBlob, buildArtifactTree, buildChatScope, collectArtifacts, collectMessageText, createChatComponentRegistry, createChatId, createChatRuntime, createChatWorkspace, createManualDriver, createSafeRegistry, detectStreamingMode, downloadArtifact, guardChatDsl, isImageArtifact, mergeArtifacts, pairToolTraces, registerCapabilityAction, registerChatComponent, registerChatLayout, registerChatShellComponent, resolveArtifactFileType, resolveArtifactFilename, runChatTurn, runRegenerateTurn, saveBlob, useChatAutoScroll, useChatServices, useSidebarDrawer, useSmoothStreamText };
package/dist/index.d.ts CHANGED
@@ -9,7 +9,9 @@ import { RefObject, ReactNode, ComponentType } from 'react';
9
9
  *
10
10
  * 零 React，可纯 Node 测试；状态语义与 ConversationStore 同模式
11
11
  * （不可变更新 + subscribe 通知，兼容 useSyncExternalStore）。
12
- * store 只持当前一个产出物：多产出物 / 历史由业务层自行管理后注入。
12
+ * store 持会话内全部产出物列表 + 当前激活项：open 按 id upsert 并
13
+ * 激活；面板 tabs / 目录列表视图经 list() 读取；close 只关闭面板
14
+ * （清空激活项），列表保留供重开时继续切换。
13
15
  */
14
16
  /** 产出物：dsl kind 的 content 为 DslNode 普通对象，其余 kind 为字符串 */
15
17
  interface ChatArtifact {
@@ -19,25 +21,66 @@ interface ChatArtifact {
19
21
  content: string | DslNode;
20
22
  /** code kind 的语言标记（仅作角标展示） */
21
23
  language?: string;
24
+ /**
25
+ * 文件类型（扩展名，大小写 / 带点均可，如 'png' / '.MD'）：
26
+ * 图片类扩展名走内建图片预览（content 为 URL / data URL，
27
+ * svg 另支持原始标记）；自定义查看器（artifactViewers）按此键匹配。
28
+ * 缺省从 title 的扩展名推导
29
+ */
30
+ fileType?: string;
22
31
  meta?: Record<string, unknown>;
23
32
  }
33
+ /** 内建图片预览的扩展名（小写不带点） */
34
+ declare const ARTIFACT_IMAGE_EXTENSIONS: readonly string[];
35
+ /** 解析产物文件类型：显式 fileType 优先，缺省取 title 扩展名；均无返回 null */
36
+ declare function resolveArtifactFileType(artifact: ChatArtifact): string | null;
37
+ /** 是否图片类产物（扩展名命中内建图片集合） */
38
+ declare function isImageArtifact(artifact: ChatArtifact): boolean;
24
39
  /** update 的补丁：id 不可改 */
25
40
  type ArtifactPatch = Partial<Omit<ChatArtifact, 'id'>>;
41
+ /** 消息形态的最小契约（与 model.ts ChatMessage 结构化兼容，保持本文件零依赖） */
42
+ interface ArtifactPartCarrier {
43
+ parts: Array<{
44
+ type: string;
45
+ artifact?: ChatArtifact;
46
+ status?: string;
47
+ }>;
48
+ }
49
+ /**
50
+ * 从会话消息流归集产出物（tabs / 目录列表视图的默认数据源）：
51
+ * 按消息序遍历 artifact part，同 id 后者覆盖（流式更新取最新），
52
+ * 顺序保持首次出现序；streaming 中的 part 跳过（就绪后再入列）。
53
+ * 纯函数，输入消息数组引用不变时结果可经 useMemo 缓存。
54
+ */
55
+ declare function collectArtifacts(messages: readonly ArtifactPartCarrier[]): ChatArtifact[];
26
56
  /**
27
- * ArtifactStore（设计决策 D1）：当前产出物的可变容器。
57
+ * 合并消息流归集与 store 打开记录：stream 顺序为主，冲突 id 取
58
+ * store 版本（store.update 的流式补丁可能领先消息 part），
59
+ * store 中未入流的产物（宿主直接 open 的）追加在后。
60
+ */
61
+ declare function mergeArtifacts(stream: readonly ChatArtifact[], opened: readonly ChatArtifact[]): ChatArtifact[];
62
+ /**
63
+ * ArtifactStore（设计决策 D1）：产出物列表的可变容器。
28
64
  * 可注入（services.artifactStore）或由组合层自持（ref 保持）。
29
65
  * 对未 open 状态下的 update 宽容：console.warn 并忽略，不抛错。
66
+ * list() 返回的内部数组不可变、引用在不变时保持稳定
67
+ * （useSyncExternalStore 快照安全）。
30
68
  */
31
69
  declare class ArtifactStore {
32
- private artifact;
70
+ private artifacts;
71
+ private activeId;
33
72
  private readonly listeners;
34
- /** 当前产出物（未打开时为 null；引用在不变时保持稳定） */
73
+ /** 当前激活产出物（未打开时为 null；引用在不变时保持稳定） */
35
74
  get(): ChatArtifact | null;
36
- /** 打开（或替换）当前产出物 */
75
+ /** 全部产出物（插入序；数组不可变，引用稳定） */
76
+ list(): ChatArtifact[];
77
+ /** 打开（或按 id 替换）产出物并激活 */
37
78
  open(artifact: ChatArtifact): void;
38
- /** 部分更新当前产出物（id 不可改）；未 open 时告警并忽略 */
79
+ /** 切换激活项（未知 id 告警并忽略，不抛错） */
80
+ activate(id: string): void;
81
+ /** 部分更新当前激活产出物（id 不可改）；未 open 时告警并忽略 */
39
82
  update(patch: ArtifactPatch): void;
40
- /** 关闭面板（未打开时幂等，不重复通知） */
83
+ /** 关闭面板：清空激活项，列表保留（未打开时幂等，不重复通知） */
41
84
  close(): void;
42
85
  /** 订阅变更；返回退订函数 */
43
86
  subscribe(listener: () => void): () => void;
@@ -261,6 +304,21 @@ declare class ConversationStore {
261
304
  private commit;
262
305
  }
263
306
 
307
+ /** 下载文件名：title 已带扩展名原样使用；否则补 fileType / kind 缺省扩展名 */
308
+ declare function resolveArtifactFilename(artifact: ChatArtifact): string;
309
+ /**
310
+ * 构建下载 Blob；图片内容为 http(s) URL 时返回 null（由 downloadArtifact
311
+ * 走 fetch 取回，失败降级新标签打开）
312
+ */
313
+ declare function buildArtifactBlob(artifact: ChatArtifact): Blob | null;
314
+ /** 触发浏览器下载（Object URL + 临时锚点） */
315
+ declare function saveBlob(blob: Blob, filename: string): void;
316
+ /**
317
+ * 下载产物：文本类 / dsl JSON / 图片 data URL 与 svg 标记直接存 Blob；
318
+ * 图片 http(s) URL fetch 取回（跨域失败降级新标签打开）
319
+ */
320
+ declare function downloadArtifact(artifact: ChatArtifact): Promise<void>;
321
+
264
322
  /**
265
323
  * Streaming 事件模型与 reducer（设计决策 D2，设计文档第 69 节）。
266
324
  *
@@ -653,6 +711,69 @@ interface UseChatAutoScrollResult {
653
711
  }
654
712
  declare function useChatAutoScroll({ messageCount, lastContentLength, isStreaming, }: UseChatAutoScrollOptions): UseChatAutoScrollResult;
655
713
 
714
+ /**
715
+ * ArtifactPanel（spec: chat-artifact-panel，设计决策 D2/D3）：
716
+ * 产出物预览面板 = 标题栏（标题 + kind 角标 + 关闭按钮）+ 内容区。
717
+ *
718
+ * 内容按 artifact.kind 分发内建渲染器：markdown 经 @pactor-app/markdown
719
+ * 安全渲染；code 只读代码块（language 仅作角标，不引高亮依赖）；
720
+ * text 预格式文本；dsl 经 guardChatDsl 白名单守卫 + renderChildren
721
+ * 活预览（与消息流 dsl part 同安全级），被拦截 / 渲染失败一律降级为
722
+ * 受控占位块（ChatDenied 同款），MUST NOT 抛错。
723
+ *
724
+ * 纯展示组件：关闭只触发 onClose，不单方面修改外部状态。
725
+ */
726
+ interface ArtifactPanelProps {
727
+ /** 当前产出物；null 时内容区为空态（inspector 槽场景常见） */
728
+ artifact?: ChatArtifact | null;
729
+ /**
730
+ * 会话内全部产出物（多产物场景）：提供后 header 左端展示目录列表
731
+ * 切换钮；多于 1 个时 header 下沿展示 tab 条（kind 图标 + 名称）
732
+ */
733
+ artifacts?: ChatArtifact[];
734
+ /** 当前激活产出物 id（tabs 高亮；缺省取 artifact.id） */
735
+ activeArtifactId?: string;
736
+ /** tab / 目录列表点击切换回调（受控切换，面板不自改外部状态） */
737
+ onSelectArtifact?: (artifact: ChatArtifact) => void;
738
+ /** 面板内容槽：提供时整体替代内建渲染器（标题栏保留） */
739
+ inspector?: ReactNode;
740
+ /** 关闭按钮 / 遮罩点击回调 */
741
+ onClose?: () => void;
742
+ /** dsl 产出物活预览的 Safe Registry；缺省时 dsl 内容渲染降级块 */
743
+ safeRegistry?: Registry<unknown>;
744
+ /** 注入 dsl 预览作用域 user */
745
+ user?: Record<string, unknown>;
746
+ /**
747
+ * 自定义产物查看器（spec: chat-artifact-panel / 自定义预览）：
748
+ * 按扩展名 / kind 对特定文件格式提供自定义预览，优先于内建渲染器
749
+ */
750
+ artifactViewers?: ArtifactViewers;
751
+ className?: string;
752
+ }
753
+ /**
754
+ * 产物目录树（纯函数）：按 id 的 '/' 分段建目录层级——
755
+ * id 形如 `reports/q3/月报` 时产出 reports → q3 两级目录；
756
+ * 无 '/' 分段的产物平铺在根层。目录先于文件、各自按名称排序。
757
+ */
758
+ interface ArtifactTreeNode {
759
+ /** 段名（目录名或产物标题） */
760
+ name: string;
761
+ /** 完整路径（目录为 id 前缀，文件为产物 id） */
762
+ path: string;
763
+ artifact?: ChatArtifact;
764
+ children: ArtifactTreeNode[];
765
+ }
766
+ declare function buildArtifactTree(artifacts: ChatArtifact[]): ArtifactTreeNode[];
767
+ /**
768
+ * 自定义产物查看器（spec: chat-artifact-panel / 自定义预览）：
769
+ * 键为扩展名（小写不带点，如 'png' / 'md'）或 kind
770
+ * （'markdown' / 'code' / 'text' / 'dsl'）；扩展名键优先于 kind 键，
771
+ * 均优先于内建渲染器。查看器抛错不经守卫——宿主代码自负。
772
+ */
773
+ type ArtifactViewer = (artifact: ChatArtifact) => ReactNode;
774
+ type ArtifactViewers = Record<string, ArtifactViewer>;
775
+ declare function ArtifactPanel({ artifact, artifacts, activeArtifactId, onSelectArtifact, inspector, onClose, safeRegistry, user, artifactViewers, className, }: ArtifactPanelProps): ReactNode;
776
+
656
777
  /**
657
778
  * EmptyState（spec: chat-empty-state，设计决策 D0/D1）：空会话欢迎页。
658
779
  *
@@ -716,6 +837,12 @@ interface ChatWorkspaceServices {
716
837
  storeFactory?: () => ConversationStore;
717
838
  /** 产出物面板 store（spec: chat-artifact-panel）；缺省包内默认构造 */
718
839
  artifactStore?: ArtifactStore;
840
+ /**
841
+ * 自定义产物查看器（spec: chat-artifact-panel / 自定义预览）：
842
+ * 按键（扩展名小写不带点，或 kind）对特定文件格式提供自定义预览，
843
+ * 优先于内建渲染器；函数不进 DSL props，统一经服务注入
844
+ */
845
+ artifactViewers?: ArtifactViewers;
719
846
  /** Safe Registry（createSafeRegistry 包装后的白名单注册表） */
720
847
  safeRegistry?: Registry<unknown>;
721
848
  /** capability 白名单与确认链 */
@@ -805,6 +932,12 @@ interface ChatWorkspaceProps {
805
932
  onArtifact?: (artifact: ChatArtifact) => void;
806
933
  /** 产出物卡片"在面板中打开"回调（runtime 绑定 events.onOpenArtifact 时传入） */
807
934
  onOpenArtifact?: (artifact: ChatArtifact) => void;
935
+ /**
936
+ * 面板 tab / 目录列表点击切换回调（runtime 绑定 events.onSelectArtifact
937
+ * 时传入；受控典型接法：setState artifact=${event.artifact}）。
938
+ * 多产物列表缺省由组合层从消息流归集，无需显式注入
939
+ */
940
+ onSelectArtifact?: (artifact: ChatArtifact) => void;
808
941
  /**
809
942
  * 内建 header 操作组（spec: chat-dsl-component / Header 配置，决策 D4）：
810
943
  * 按数组顺序渲染（headerExtra 槽之前）；缺省不渲染
@@ -981,6 +1114,8 @@ interface ChatProps {
981
1114
  onArtifact?: (artifact: ChatArtifact) => void;
982
1115
  /** 产出物卡片"在面板中打开"按钮点击回调（event 作用域含 artifact；受控场景的开面板入口） */
983
1116
  onOpenArtifact?: (artifact: ChatArtifact) => void;
1117
+ /** 面板 tab / 目录列表点击切换回调（event 作用域含 artifact；受控典型接法：setState artifact=${event.artifact}） */
1118
+ onSelectArtifact?: (artifact: ChatArtifact) => void;
984
1119
  className?: string;
985
1120
  /** 发送回调：与 transport 驱动 turn 并行（同 ChatView onSend 语义） */
986
1121
  onSend?: (text: string) => void;
@@ -1010,7 +1145,7 @@ declare function ChatSidebarMenu({ menu, activeMenuKey, onMenuSelect, }: {
1010
1145
  * 「未配置聊天服务」提示并 console.warn，不抛错。组合逻辑与
1011
1146
  * createChatWorkspace 共用内部 ChatComposition（决策 D5）。
1012
1147
  */
1013
- declare function Chat({ title, greeting, subtitle, suggestions, conversationId, params, showHeader, menu, activeMenuKey, sidebar, toolbarStart, toolbarEnd, composerFooter, composerBottom, hideToolbar, headerExtra, header, headerActions, editableTitle, onExport, onThemeChange, onClear, onTitleChange, models, model, onModelChange, modelPlacement, contexts, onContextsChange, messageActions, onMessageAction, artifact, panelOpen, onPanelClose, inspector, onArtifact, onOpenArtifact, className, onSend, onMenuSelect, }: ChatProps): ReactNode;
1148
+ declare function Chat({ title, greeting, subtitle, suggestions, conversationId, params, showHeader, menu, activeMenuKey, sidebar, toolbarStart, toolbarEnd, composerFooter, composerBottom, hideToolbar, headerExtra, header, headerActions, editableTitle, onExport, onThemeChange, onClear, onTitleChange, models, model, onModelChange, modelPlacement, contexts, onContextsChange, messageActions, onMessageAction, artifact, panelOpen, onPanelClose, inspector, onArtifact, onOpenArtifact, onSelectArtifact, className, onSend, onMenuSelect, }: ChatProps): ReactNode;
1014
1149
  /** Chat 的 DSL 组件类型名 */
1015
1150
  declare const CHAT_COMPONENT_TYPE = "Chat";
1016
1151
  /**
@@ -1073,33 +1208,6 @@ declare const CHAT_SHELL_COMPONENT_TYPE = "ChatShell";
1073
1208
  */
1074
1209
  declare function registerChatShellComponent(registry: Registry<unknown>): void;
1075
1210
 
1076
- /**
1077
- * ArtifactPanel（spec: chat-artifact-panel，设计决策 D2/D3）：
1078
- * 产出物预览面板 = 标题栏（标题 + kind 角标 + 关闭按钮）+ 内容区。
1079
- *
1080
- * 内容按 artifact.kind 分发内建渲染器：markdown 经 @pactor-app/markdown
1081
- * 安全渲染；code 只读代码块（language 仅作角标，不引高亮依赖）；
1082
- * text 预格式文本；dsl 经 guardChatDsl 白名单守卫 + renderChildren
1083
- * 活预览（与消息流 dsl part 同安全级），被拦截 / 渲染失败一律降级为
1084
- * 受控占位块（ChatDenied 同款），MUST NOT 抛错。
1085
- *
1086
- * 纯展示组件：关闭只触发 onClose，不单方面修改外部状态。
1087
- */
1088
- interface ArtifactPanelProps {
1089
- /** 当前产出物；null 时内容区为空态（inspector 槽场景常见） */
1090
- artifact?: ChatArtifact | null;
1091
- /** 面板内容槽：提供时整体替代内建渲染器（标题栏保留） */
1092
- inspector?: ReactNode;
1093
- /** 关闭按钮 / 遮罩点击回调 */
1094
- onClose?: () => void;
1095
- /** dsl 产出物活预览的 Safe Registry；缺省时 dsl 内容渲染降级块 */
1096
- safeRegistry?: Registry<unknown>;
1097
- /** 注入 dsl 预览作用域 user */
1098
- user?: Record<string, unknown>;
1099
- className?: string;
1100
- }
1101
- declare function ArtifactPanel({ artifact, inspector, onClose, safeRegistry, user, className, }: ArtifactPanelProps): ReactNode;
1102
-
1103
1211
  /**
1104
1212
  * 侧栏抽屉 context（spec: chat-app-shell）：侧栏内容（如导航项）在导航后
1105
1213
  * 调用 `close()` 关闭移动端抽屉；不在 AppShell 内时返回 null，
@@ -1346,7 +1454,9 @@ declare function ChatView({ store, transport, onSend, safeRegistry, capabilities
1346
1454
  * 答案阶段自动折叠，用户操作后 pin。
1347
1455
  *
1348
1456
  * 折叠状态机（每条消息独立，随组件实例记忆）：`auto | pinned-open |
1349
- * pinned-closed`——auto 跟随流式阶段；用户点击后 pin，不再自动变更。
1457
+ * pinned-closed`——auto 跟随流式阶段但带单向闩锁（自动折叠一次后
1458
+ * 不再自动展开，防止 mode 回跳引起展开/折叠闪烁）；用户点击后 pin，
1459
+ * 不再自动变更。
1350
1460
  */
1351
1461
  interface ActivityTraceProps {
1352
1462
  message: ChatMessage;
@@ -1493,4 +1603,4 @@ interface ChatLayoutRegistry {
1493
1603
  /** 注册 chat 布局（已注册时不覆盖，与 createLayoutRegistry 约定一致） */
1494
1604
  declare function registerChatLayout(layoutRegistry: ChatLayoutRegistry): void;
1495
1605
 
1496
- export { ActivityTrace, type ActivityTraceProps, AppShell, type AppShellProps, ArtifactPanel, type ArtifactPanelProps, type ArtifactPatch, ArtifactStore, type BuiltinMessageAction, CHAT_COMPONENT_TYPE, CHAT_DENIED_TYPE, CHAT_LAYOUT_TYPE, CHAT_SHELL_COMPONENT_TYPE, type CapabilityActionDeps, type CapabilityHandler, Chat, type ChatArtifact, type ChatAttachment, type ChatCapabilityRegistry, type ChatConfirm, type ChatConfirmRequest, type ChatContextItem, type ChatContextSource, ChatDenied, type ChatEvent, type ChatHeaderAction, type ChatInput, ChatLayout, type ChatLayoutProps, type ChatLayoutRegistry, type ChatMenuItem, type ChatMessage, type ChatMessageAction, type ChatModelOption, type ChatPart, type ChatPermissionChecker, type ChatProps, type ChatRole, type ChatRuntime, type ChatScope, type ChatServices, ChatServicesProvider, ChatShell, type ChatShellProps, ChatSidebarMenu, type ChatSuggestion, type ChatTransport, type ChatTurnResult, ChatView, type ChatViewProps, type ChatWorkspaceProps, type ChatWorkspaceServices, Composer, type ComposerProps, ConversationStore, type CreateChatRuntimeOptions, DEFAULT_CHAT_GREETING, EmptyState, type EmptyStateProps, type ManualChatDriver, MessageActions, type MessageActionsProps, MessageBubble, type MessageBubbleProps, type MessagePatch, type MessageStatus, type PartPatch, type PartRef, PartRenderer, type PartRendererProps, type PartStatus, type RunChatTurnOptions, type StreamingMode, type ToolCallStatus, type ToolTraceEntry, type UseChatAutoScrollOptions, type UseChatAutoScrollResult, type UseSmoothStreamTextOptions, applyChatEvent, buildChatScope, collectMessageText, createChatComponentRegistry, createChatId, createChatRuntime, createChatWorkspace, createManualDriver, createSafeRegistry, detectStreamingMode, guardChatDsl, pairToolTraces, registerCapabilityAction, registerChatComponent, registerChatLayout, registerChatShellComponent, runChatTurn, runRegenerateTurn, useChatAutoScroll, useChatServices, useSidebarDrawer, useSmoothStreamText };
1606
+ export { ARTIFACT_IMAGE_EXTENSIONS, ActivityTrace, type ActivityTraceProps, AppShell, type AppShellProps, ArtifactPanel, type ArtifactPanelProps, type ArtifactPatch, ArtifactStore, type ArtifactTreeNode, type ArtifactViewer, type ArtifactViewers, type BuiltinMessageAction, CHAT_COMPONENT_TYPE, CHAT_DENIED_TYPE, CHAT_LAYOUT_TYPE, CHAT_SHELL_COMPONENT_TYPE, type CapabilityActionDeps, type CapabilityHandler, Chat, type ChatArtifact, type ChatAttachment, type ChatCapabilityRegistry, type ChatConfirm, type ChatConfirmRequest, type ChatContextItem, type ChatContextSource, ChatDenied, type ChatEvent, type ChatHeaderAction, type ChatInput, ChatLayout, type ChatLayoutProps, type ChatLayoutRegistry, type ChatMenuItem, type ChatMessage, type ChatMessageAction, type ChatModelOption, type ChatPart, type ChatPermissionChecker, type ChatProps, type ChatRole, type ChatRuntime, type ChatScope, type ChatServices, ChatServicesProvider, ChatShell, type ChatShellProps, ChatSidebarMenu, type ChatSuggestion, type ChatTransport, type ChatTurnResult, ChatView, type ChatViewProps, type ChatWorkspaceProps, type ChatWorkspaceServices, Composer, type ComposerProps, ConversationStore, type CreateChatRuntimeOptions, DEFAULT_CHAT_GREETING, EmptyState, type EmptyStateProps, type ManualChatDriver, MessageActions, type MessageActionsProps, MessageBubble, type MessageBubbleProps, type MessagePatch, type MessageStatus, type PartPatch, type PartRef, PartRenderer, type PartRendererProps, type PartStatus, type RunChatTurnOptions, type StreamingMode, type ToolCallStatus, type ToolTraceEntry, type UseChatAutoScrollOptions, type UseChatAutoScrollResult, type UseSmoothStreamTextOptions, applyChatEvent, buildArtifactBlob, buildArtifactTree, buildChatScope, collectArtifacts, collectMessageText, createChatComponentRegistry, createChatId, createChatRuntime, createChatWorkspace, createManualDriver, createSafeRegistry, detectStreamingMode, downloadArtifact, guardChatDsl, isImageArtifact, mergeArtifacts, pairToolTraces, registerCapabilityAction, registerChatComponent, registerChatLayout, registerChatShellComponent, resolveArtifactFileType, resolveArtifactFilename, runChatTurn, runRegenerateTurn, saveBlob, useChatAutoScroll, useChatServices, useSidebarDrawer, useSmoothStreamText };