@pactor-app/chat 1.15.6 → 1.17.0

package/README.md

@@ -63,7 +63,7 @@ driver.complete();
 ## API 一览
 
 - **`ConversationStore`**（零 React）：`appendMessage` / `updateMessage(id, patch)` / `appendPart(messageId, part)` / `updatePart(messageId, partRef, patch)`（partRef 为下标或 part id）/ `setStatus` / `removeMessagesFrom(messageId)`（不可变截断该消息及之后全部消息，编辑重发/重新生成的基础）/ `clear` / `subscribe(listener)`。全部更新不可变（新数组引用），兼容 `useSyncExternalStore`。`ChatMessage` 支持 `attachments?: ChatAttachment[]`（`id`/`name`/`mimeType`/`size?`/`url?`，上传与存储由调用方负责）。
-- **`applyChatEvent(store, event)`**（零 React）：Streaming 纯 reducer。事件：`message.start` / `text.delta`（`format: 'markdown'` 建 markdown part）/ `thinking.delta` / `tool.start`（可携带 `args`，供活动轨迹参数摘要）/ `tool.result` / `dsl.start` / `dsl.complete` / `message.end` / `message.error`。对乱序宽容（delta 先于 start 自动建占位）、未知事件忽略并告警；`dsl.patch` V1 不实现。
+- **`applyChatEvent(store, event)`**（零 React）：Streaming 纯 reducer。事件：`message.start` / `text.delta`（`format: 'markdown'` 建 markdown part）/ `thinking.delta` / `tool.start`（可携带 `args`，供活动轨迹参数摘要）/ `tool.result` / `dsl.start` / `dsl.complete` / `artifact`（一次性写入 ready 的产出物 part；partId 命中既有 part 时原地更新）/ `message.end` / `message.error`。对乱序宽容（delta 先于 start 自动建占位）、未知事件忽略并告警；`dsl.patch` V1 不实现。
 - **`ChatTransport` / `runChatTurn(store, transport, input)`**：`send({ text, conversationId? }) → AsyncIterable<ChatEvent>`；turn 先 append user 消息 + assistant 占位再逐事件 reduce，transport 抛错收敛为 `message.error`。`createManualDriver()` 提供代码控制推送事件的 transport（`push` / `complete` / `fail`），测试与手动驱动共用。
 - **`runRegenerateTurn(store, transport, options?)`**（零 React）：定位末条 user 消息 → `removeMessagesFrom` 截断其后消息 → 以同文本重跑 turn（`options.skipUserMessage`，不重复追加 user 消息）；支持 `signal` 取消；无 user 消息时告警返回。消息操作条的"重新生成 / 错误重试"即接入此函数。
 - **`detectStreamingMode(message)` / `pairToolTraces(parts)`**（零 React 纯函数）：活动轨迹的推导层——前者返回 `reasoning | tool | responding | null`；后者把 tool-call 与 tool-result 按 name + 出现顺序配对为 `ToolTraceEntry`（名称 / 参数 / 状态 / part 下标）。
@@ -71,8 +71,11 @@ driver.complete();
 - **`registerCapabilityAction(actions, { capabilities, permission?, confirm? })`**：注册 `capability` 动作，执行链 registry → permission → confirm（`risk: 'high'` 且注入 confirm 时；取消返回 `{ ok: true, skipped: true }`，未注入 confirm 受控拒绝）→ execute。DSL 侧：`{ action: 'capability', params: { name, params } }`。
 - **`createChatRuntime({ safeRegistry, capabilities?, permission?, permissionStore?, confirm?, user? })`**：组装 Chat DSL 渲染运行时（Safe Registry + 内置动作 + capability 动作 + 权限适配器）；`buildChatScope({ conversation, message, params })` 组装 chat 作用域（`user` 经 RuntimeContext 注入）。
 - **`<ChatView store transport? onSend? safeRegistry? capabilities? permission? confirm? conversationId? user? params? greeting? subtitle? suggestions?>`**：消息列表 + Composer。发送时 `onSend` 回调先行，注入 `transport` 时同时驱动一轮 turn。空会话渲染 `<EmptyState>`：问候语（`--pactor-chat-font-display` 衬线展示字体）+ 副标题 + `suggestions` 起始建议（字符串或 `{ label, prompt? }`，点击即发送，空数组不渲染建议区）。Composer 扩展 props（`attachments` / `onAttachmentsChange` / `onAttachFiles` / `onAttachmentClick` / `toolbarStart` / `toolbarEnd` / `onMentionTrigger` / `onPlusMenu`）原样透传给内建 Composer，语义见下方 `<Composer>`。
-- **`<MessageBubble>` / `<PartRenderer>`**：按 role 区分气泡；parts 按类型渲染（text / markdown / dsl / thinking 折叠卡：流式展开 + 进行中指示、答案阶段自动折叠、支持 pin / error 附重试入口 / status）；tool-call / tool-result 移交 `<ActivityTrace>` 配对渲染。
-- **`<ActivityTrace>`**：流式状态头（动画图标 + 呼吸文案 + 秒级计时，结束定格）+ 配对工具轨迹条目（单行：名称 + 参数摘要 + 状态图标，展开显示参数与结果/错误）；流式展开 → 答案阶段自动折叠 → 用户 pin 后不再自动变更（按消息记忆）。
+- **`<MessageBubble>` / `<PartRenderer>`**：按 role 区分气泡；parts 按类型渲染（text / markdown / dsl / error 附重试入口 / status / artifact 产出物卡片——整卡可点击：着色图标盒 + 标题 + 元信息行「尺寸 · 类型」+ 右上箭头，图标经 `resolveArtifactIcon` 按扩展名优先、kind 兜底解析并带 tone 着色档位，与面板下拉 / 目录树一致；卡片即 `ChatArtifactCard` 内部组件，DSL 片段与 fallback 共用，包入口导出可直接复用；同一消息内连续 artifact part 归并为卡片组，多于 4 个收起为前 4 张 + 「展开 / 收起」与「查看所有产物（n) ›」（打开面板定位产物目录视图，回调 `onOpenArtifactList`））；thinking 折叠卡与 tool-call / tool-result 配对轨迹移交 `<ActivityTrace>`；assistant 终态消息底部展示时间戳（当天 HH:mm、非当天带日期，`formatMessageTime`；流式中与无 createdAt 的历史消息不展示，user / system 不展示）。
+- **`<ActivityTrace>`**：流式状态头（动画图标 + 呼吸文案 + 秒级计时，结束定格）+ 配对工具轨迹条目（单行：名称 + 参数摘要 + 状态图标，展开显示参数与结果/错误）+ thinking 折叠卡（与工具列表为独立块）；状态头统一折叠/展开全部内容——流式展开 → 答案阶段自动折叠（单向闩锁：折叠一次后 mode 回跳不重新自动展开，防闪烁）→ 用户 pin 后不再自动变更（按消息记忆）。
+- **`<ArtifactPanel artifact? artifacts? inspector? artifactViewers? onClose? onSelectArtifact?>`**：产出物预览面板——标题栏（可选目录列表钮 + 标题 + kind 角标 + 下载钮 + 关闭钮）+ 内容区。内建渲染 markdown / code / text / dsl（Safe Registry 活预览）+ 图片类文件（png / jpg / svg / webp 等，经 `fileType` 或 title 扩展名识别，svg 支持原始标记）；`artifactViewers` 按键（扩展名 / kind）对特定格式自定义预览，优先内建；多产物时 header 文件名处为切换下拉，左端目录钮展示产物目录列表（目录视图下返回钮隐藏、标题显示"产物目录"）；下载钮把当前产物存为本地文件（dsl 存 JSON，图片 URL fetch 失败降级新标签）；桌面固定宽右栏（默认宽 = `--pactor-chat-content-width`，宽度夹取 `--pactor-chat-inspector-min-width` 480px ~ host 宽 2/3），背景 `--pactor-chat-inspector-bg` 略深于聊天区，窄屏覆盖抽屉。
+- **`ArtifactStore` / `collectArtifacts` / `mergeArtifacts`**（零 React）：产出物列表容器——`open` 按 id upsert 并激活、`list()`（引用稳定）/ `activate(id)` / `update(patch)`（补丁激活项）/ `close()`（只关面板，列表保留）/ `subscribe`；`collectArtifacts(messages)` 从消息流归集 ready 产出物（tabs / 目录列表默认数据源），`mergeArtifacts(stream, opened)` 合并归集与打开记录（store 补丁版本优先）。
+- **`downloadArtifact` / `resolveArtifactFilename` / `buildArtifactBlob`**（产物下载）：文件名按 title（无扩展名补 fileType / kind 缺省）；文本类存 UTF-8 Blob，dsl 存格式化 JSON，svg 原始标记存 image/svg+xml，图片 http(s) URL fetch 取回（失败降级新标签打开）。
 - **`<MessageActions>`**：消息操作条（hover 显现），数据驱动渲染——`actions` 缺省为 `['copy', 'regenerate', 'retry', 'edit']`：复制（`collectMessageText` 汇总文本写入剪贴板）、末条 completed assistant 重新生成、user 消息气泡内联编辑重发（确认 → 截断 + 重跑，取消不改 store）、error 消息重试。传入数组时严格按数组渲染（数组即真相），内建动作可按字段覆盖 label / icon / roles / visibleWhen，自定义动作经 `callService(service, { actionId, message })` 派发；图标名走 `MESSAGE_ACTION_ICONS` 白名单（未知名渲染占位图标）。详见下文「消息操作条：messageActions」。
 - **`<Composer>`**：自适应高度 textarea；IME 合成守卫（合成中 Enter 不发送）；发送按钮状态机（disabled / ready / streaming 停止，同元素切换 + 纯 CSS 光环）；受控附件 `attachments` + `onAttachmentsChange`（图片缩略图/文档卡片 + 移除），拖拽悬停态、粘贴与文件选择产出 `File[]` 经 `onAttachFiles` 交给调用方（包内不上传），点击卡片经 `onAttachmentClick` 通知；`toolbarStart` / `toolbarEnd` 渲染槽；词边界 `@` 触发 `onMentionTrigger(query, anchorRect)`，"+" 按钮触发 `onPlusMenu(anchorRect)`（未传回调不渲染入口，弹层由调用方实现）。
 - **`<AppShell sidebar brand? locationKey? className?>`**：应用外壳——侧栏插槽 + 主区。桌面（≥768px）侧栏与主区 flex 同行；移动端（<768px）侧栏退出文档流变为覆盖抽屉（遮罩 + 顶栏菜单按钮 + `brand` 品牌区），断点由 CSS 媒体查询表达，JS 只管开合。抽屉打开时 Escape / 遮罩点击关闭；`locationKey` 变化（路由 / 会话切换）渲染期自动关闭；移动端关闭时侧栏容器 `inert`。侧栏内容经 `useSidebarDrawer()` 取 `{ close }`（壳外返回 null），导航后可关闭抽屉。
@@ -133,8 +136,9 @@ body:
 ```
 
 - **菜单**：`menu: ChatMenuItem[]`（`key / label / icon? / badge? / disabled? / group?`）驱动内建侧栏；`icon` 为字符串名，映射内置 lucide 子集（plus / chat / history / settings / star / search / user / folder），未知名渲染占位圆点不抛错；`group` 渲染分组标题行；`activeMenuKey` 为受控 prop，典型用法是 `${state.x}` 绑定 + `events.onMenuSelect` 调 `setState` 闭环；disabled 项不触发 `onMenuSelect`。
-- **Header 三层**：`title` 标量 → `headerExtra?: DslNode | ReactNode`（标题右侧槽）→ `header?: DslNode | ReactNode`（整体替换内建 header）；`showHeader: false` 关闭。DslNode 槽仅在页面运行时（DslRenderer）上下文内经 `useRenderer().renderChildren` 渲染；纯 React 场景传 ReactNode，误传 DslNode 时告警并跳过（不抛错）。
+- **Header 三层**：`title` 标量 → `headerExtra?: DslNode | ReactNode`（标题右侧槽）→ `header?: DslNode | ReactNode`（整体替换内建 header）；`showHeader: false` 关闭。header 渲染为全宽容器（产物面板 host / with-header 包裹层）的直接子级，不随对话列限宽——产物面板调宽时保持通栏。DslNode 槽仅在页面运行时（DslRenderer）上下文内经 `useRenderer().renderChildren` 渲染；纯 React 场景传 ReactNode，误传 DslNode 时告警并跳过（不抛错）。
 - **侧栏槽**：`sidebar?: DslNode | ReactNode` 提供时整体替代内建菜单侧栏（仍以 AppShell 承载）。
+- **产出物面板**：`artifact` / `panelOpen` 受控 props（典型 `${state.x}` 绑定），事件 `onArtifact`（part 就绪）/ `onOpenArtifact`（卡片打开）/ `onOpenArtifactList`（卡片区"查看所有产物"，典型接法 `setState panelOpen=true`，面板自动定位产物目录视图）/ `onPanelClose` / `onSelectArtifact`（下拉 / 目录列表切换，典型接法 `setState artifact=${event.artifact}`）；多产物清单由组合层自动从消息流归集，无需 DSL 接线；自定义预览经 `ChatServicesProvider` 注入 `artifactViewers`（函数不进 DSL）。详见上文 `<ArtifactPanel>` 与 `examples/chat/src/chat.page.yaml`。
 - **React 直连**：`<ChatServicesProvider>` + `<Chat>` 同样可直接作为 React 组件使用（events 即普通函数 props：`onSend?(text)` / `onMenuSelect?(key, item)`）。`createChatWorkspace` 工厂保留为兼容路径，内部已改为 provider + 同一组合逻辑（`ChatComposition`），行为不变。
 
 ### 消息操作条：messageActions