@qfei-design/make-ai-assistant 0.1.4 → 0.1.5

package/PUBLIC_API.md

@@ -25,6 +25,7 @@
 - `reduceAssistantEvent`
 - `parseAssistantEvent`
 - `AssistantTransport`
+- `AssistantRegenerateRequest`
 - `AssistantEvent`
 - `MakeAiArtifact` 及所有 V1 Artifact 类型
 - `MakeAssistantHostContext`
@@ -38,10 +39,12 @@ Fetch SSE 实现时，从 `/sse` 入口导入 `createSseAssistantTransport`。
 
 - `MakeAiAssistant`：默认浮动入口与右侧抽屉；支持受控开关、自定义 launcher，以及
   `brandName` 对默认“{品牌名} AI 助手”标题的覆盖。`title` 可覆盖完整标题；`assistantName` /
-  `userName` 可覆盖双方消息显示名称，`userAvatarUrl` 可显示当前登录人头像。
+  `userName` 可覆盖双方消息显示名称，`userAvatarUrl` 可显示当前登录人头像。省略
+  `suggestions` 时显示包内默认推荐问题，传入 `[]` 时隐藏推荐问题。
 - `AssistantPanel`：不带 Drawer 的嵌入式会话面板；支持 `brandName`、`title`、`assistantName` /
   `userName` / `userAvatarUrl`。默认品牌为“Make”，默认显示“AI 助手”和“你”。这些字段只参与
-  本地 React 渲染，不会进入 transport 请求。
+  本地 React 渲染，不会进入 transport 请求。嵌入式面板包含复制回答、可选安全重新生成、
+  回到最新消息、可折叠处理步骤、错误重试、键盘提交与 reduced-motion 处理。
 - `ArtifactRenderer`：注册表驱动的单 Artifact 渲染器。
 - `createPlatformArtifactRegistry`
 - `platformArtifactTemplates`
@@ -55,6 +58,12 @@ Fetch SSE 实现时，从 `/sse` 入口导入 `createSseAssistantTransport`。
 Promise rejection。`onActionError` 自身同步抛错或返回 rejected Promise 时也会被包隔离，
 不会污染宿主的全局未处理异常。
 
+成功回答的“复制回答”只复制该 assistant message 的文本内容；复制失败只在本地 UI 反馈并记录
+不含回答正文的错误类型。只有当 `transport.regenerate()` 存在且 `features.regeneration`
+没有显式关闭时，“重新生成”才会显示；它会复用该回答前一条用户消息和旧 assistant message
+发起替换请求，并在当前 UI 中替换旧回答，不额外插入重复的用户气泡。用户滚离底部时，UI 不会
+强制自动跳到底部，而是显示“回到最新消息”按钮。
+
 ## AssistantTransport
 
 ```ts
@@ -62,6 +71,7 @@ interface AssistantTransport {
   readonly features?: Partial<{
     history: boolean;
     newConversation: boolean;
+    regeneration?: boolean;
     remoteCancellation: boolean;
   }>;
   loadConversation?(
@@ -72,11 +82,17 @@ interface AssistantTransport {
     request: AssistantRunRequest,
     options?: { signal?: AbortSignal },
   ): AsyncIterable<AssistantEvent>;
+  regenerate?(
+    request: AssistantRegenerateRequest,
+    options?: { signal?: AbortSignal },
+  ): AsyncIterable<AssistantEvent>;
 }
 ```
 
 `loadConversation` 存在时，面板会先进入初始化状态并恢复历史；失败时展示可重试状态。
-`features` 决定 UI 是否展示新建会话，以及停止按钮应表达“远程取消”还是仅“停止接收”。
+`regenerate` 存在时，面板才会展示成功回答的“重新生成”。该请求必须具备服务端替换旧回答或
+不追加重复用户消息的语义，不能简单映射到普通 `sendMessage`。`features` 决定 UI 是否展示
+新建会话、是否关闭重新生成，以及停止按钮应表达“远程取消”还是仅“停止接收”。
 历史快照最多接受 200 条消息、1,000,000 字符正文和 500 个 Artifact；同一条历史消息内
 Artifact id 必须唯一，避免恢复后产生重复渲染 key。
 
@@ -95,15 +111,16 @@ SSE 流必须以 `run.complete`、`run.cancelled` 或 `error` 结束。连接在
 被视为可重试的 transport 错误，避免 UI 永久停留在 streaming 状态。终止事件、解析
 失败、超限、Abort 和消费者提前结束都会取消并释放 response reader。
 
-用户输入与单次响应文本默认各限制为 100,000 字符，历史正文总预算默认 1,000,000
-字符。Artifact 的集合、字符串、JSON 深度/节点/累计文本和校验问题数量也有固定预算；
+用户输入与单次响应文本默认各限制为 100,000 字符，单次处理步骤最多 50 条且累计
+20,000 字符，历史正文总预算默认 1,000,000 字符。Artifact 的集合、字符串、JSON
+深度/节点/累计文本和校验问题数量也有固定预算；
 超限输入或历史快照会被拒绝，不会继续遍历或进入 React 模板。React UI 会在消费任意
 `AssistantTransport` 时再次调用 `parseArtifact`，自定义 transport 也不能绕过运行时白名单。
 
 自定义 transport 抛出的任意异常不会直接展示给用户；UI 只展示包自身的可控校验/
 限制消息或通用“连接失败，请重试”，完整内部错误应由宿主在 transport 边界记录。
 
-单个 run 最多接收 20 条 assistant message 和 50 个 Artifact。根入口、`/sse` 和
+单个 run 最多接收 20 条 assistant message、50 个 Artifact 和 50 条处理步骤。根入口、`/sse` 和
 `/testing` 可在没有安装 React 的 headless/Node 工程中单独使用；React 与 ReactDOM 是
 可选 peer，只有使用 `/react` 时才需要安装。
 
@@ -116,7 +133,8 @@ UI 会拒绝孤立、迟到、重复或跨 run 混入的事件，避免静默丢
 字段白名单、必填值、identifier 长度与 Artifact；宿主 adapter 也可以直接复用该函数。
 
 `message.replace` 用于服务端发送完整响应快照并替换已累积文本；`run.progress` 用于展示
-“正在查询记录”等过程状态，不写入最终消息正文。二者都受统一文本预算和事件顺序校验。
+“正在查询记录”等过程状态，并在 React UI 中累积为可折叠步骤。过程状态保留在对应 AI 回合下，
+但不写入最终消息正文。步骤超限会进入可重试错误状态，避免异常 transport 让面板无界增长。
 
 ## Make App transport
 
@@ -132,7 +150,9 @@ UI 会拒绝孤立、迟到、重复或跨 run 混入的事件，避免静默丢
 每个异步回调都会收到可选 `AbortSignal`。具体 URL、请求方法、认证、Cookie、租户与当前
 用户解析均属于宿主边界；包不提供默认路径，也不缓存可能跨身份失效的会话定位结果。
 adapter 会校验宿主响应并归一化事件，但不生成 Artifact；在后端加入版本化结构结果前，
-真实链路只渲染文本和进度。
+真实链路只渲染文本和进度。当前 Make App adapter 不实现 `regenerate()`，因为现有
+`sendMessage({ chatId, messageId, text })` 语义会持久化新的用户消息，不能安全表达
+“替换旧回答”。
 `historyLimit` 可配置为 1 到 100；`maxEventCharacters` 控制单个 EventSource `data` 的
 最大字符数，默认 1,000,000，超限会在 `JSON.parse` 前终止本次流并关闭 EventSource。
 
@@ -156,7 +176,8 @@ adapter 默认选择第一个启用的 Agent，也允许宿主用 `selectAgent`
 该入口不拼接 `/api/make/console/v1` URL、不访问 Cookie，也不导入认证 SDK。Console 宿主
 必须通过已有认证请求边界解包普通响应的 `data`，并创建 `withCredentials: true` 的
 EventSource。输入上限为 4000 个 Unicode 字符；历史最多读取 200 条，SSE 单事件默认上限
-为 1,000,000 字符。
+为 1,000,000 字符。当前 Make Console adapter 不实现 `regenerate()`，因为 Console
+`sendMessage` 同样会形成新的用户消息。
 
 ## Host responsibilities
 

package/README.md

@@ -40,6 +40,16 @@ export function AppAssistant() {
 `assistantName` 可覆盖双方消息显示名称，`userAvatarUrl` 可展示当前登录人的头像。这些显示配置
 只用于 React UI，不会随会话上下文发送到 AI transport；进度和可重试错误会显示在对应的 AI 回合中。
 
+成功的 AI 回答会显示“复制回答”；复制只处理该回答的文本内容，失败时会在本地 UI 内提示，
+不会把回答正文写入日志。只有当宿主 transport 实现可安全替换旧回答的 `regenerate()` 时，
+UI 才显示“重新生成”，并复用该回答前一条用户问题替换旧回答，不额外插入重复的用户气泡。
+用户滚离底部后，面板会显示“回到最新消息”，避免在阅读历史时强制跳到底部。
+
+`run.progress` 会累积为可折叠的处理步骤。流式生成中步骤默认展开，完成后默认折叠并保留在
+对应 AI 回合下；这些过程文本不进入最终回答正文。单次处理步骤最多 50 条且累计 20,000 字符，
+超限会进入可重试错误状态。`suggestions` 省略时使用包内默认推荐问题，传入自定义数组时使用
+宿主内容，传入 `[]` 时隐藏推荐问题。
+
 ## Package provides
 
 - Artifact V1 类型、运行时校验与 JSON Schema；
@@ -98,7 +108,9 @@ const registry = createPlatformArtifactRegistry([
 
 ## Transport
 
-`AssistantTransport.run()` 接收消息、上下文和前端能力目录，返回 `AsyncIterable<AssistantEvent>`。Mock、原生 SSE 和 AG-UI 都应适配到同一合同，因此更换后端不会改 UI。
+`AssistantTransport.run()` 接收消息、上下文和前端能力目录，返回 `AsyncIterable<AssistantEvent>`。
+如后端支持“替换已有回答”语义，可额外实现 `AssistantTransport.regenerate()`；UI 只在该能力存在时
+显示“重新生成”。Mock、原生 SSE 和 AG-UI 都应适配到同一合同，因此更换后端不会改 UI。
 
 标准 SSE 后端可直接使用：
 
@@ -133,6 +145,8 @@ const assistantTransport = createMakeAppAssistantTransport({
 该 adapter 会按 App 定位持久会话、加载最近历史、提交消息，并把
 `response.delta/progress/message/completed/failed` 归一化为包内事件。当前后端不提供
 新建会话与远程取消，因此 UI 会隐藏“新建对话”，停止操作只关闭本地 EventSource。
+当前 adapter 也不提供 `regenerate()`，避免用普通 `sendMessage` 伪装重新生成后在持久历史中
+产生重复用户消息。
 具体 URL、认证方式、租户和当前用户解析全部由宿主实现；adapter 不缓存跨调用会话定位结果。
 Make App 历史恢复同样受包级预算保护：最多 200 条历史消息、1,000,000 字符历史正文和
 500 个历史 Artifact；单个 EventSource `data` 默认不能超过 1,000,000 字符，超限会在
@@ -161,7 +175,8 @@ const assistantTransport = createMakeConsoleAssistantTransport({
 按宿主上下文选择。它会幂等定位当前用户 Session、从持久事件恢复历史、把
 `output_text.delta` 归一化为文本增量，并在 `response.completed` 后读取持久事件完成最终
 对账。收到 `fallback` 或发送结果没有可订阅 Run 时，会从用户消息 `seq + 1` 开始轮询持久
-事件。Console 输入按后端合同限制为 4000 个 Unicode 字符。
+事件。Console 输入按后端合同限制为 4000 个 Unicode 字符。当前 Console adapter 不提供
+`regenerate()`，避免用普通 `sendMessage` 伪装重新生成后在持久历史中产生重复用户消息。
 
 Console 宿主负责把这些语义回调映射到 `/api/make/console/v1`，并通过现有登录体系使用
 `credentials: "include"` / `withCredentials: true`。包不会读取、写入或复制 `zs_session`。