@qfei-design/make-ai-assistant 0.2.8 → 0.2.10

package/PUBLIC_API.md

@@ -69,11 +69,10 @@ Fetch SSE 实现时，从 `/sse` 入口导入 `createSseAssistantTransport`。
 - `ReactArtifactTemplateRegistry`
 - `formatArtifactValue`
 
-`MakeAiAssistant`、`AssistantPanel` 和 `ArtifactRenderer` 均支持 `theme?: MakeAiTheme`。标题栏、内容背景、正文、通用边框和用户消息的默认色固定，
-不会因宿主主题色变化：标题栏与承载面为白色，内容区为 `#f7f9fc`，正文为 `#15233d`，用户发送消息为
-`#2f6df6` 蓝底白字。主题色只用于竖线、圆点、图标、输入框焦点、发送按钮和标签等强调元素。`primary` 为必填，
+`MakeAiAssistant`、`AssistantPanel` 和 `ArtifactRenderer` 均支持 `theme?: MakeAiTheme`。标题栏、内容区背景与用户提问气泡默认跟随宿主主题色；输入承载面固定白色，正文、通用边框保持包内中性色。
+除标题栏、内容区背景与用户提问气泡外，主题色只用于竖线、圆点、图标、输入框焦点、发送按钮和标签等强调元素；Markdown 表格滚动条固定为中性灰。`primary` 为必填，
 `primaryHover` 与 `onPrimary` 可选；内置强调色依次读取 `theme` 属性、`--make-ai-theme-primary` 系列、
-`--make-ai-accent`、宿主 `--make-color-primary` 和包内默认值。`background`、`surface`、`surfaceStrong`、
+`--make-ai-accent`、宿主 `--make-color-primary` 和包内默认值。`background` 会控制内容区基础背景；`surface`、`surfaceStrong`、
 `text`、`textSecondary`、`border`、`overlay` 与 `onOverlay` 为兼容保留字段，不再改变内置默认样式，
 但会继续写入局部 `--make-ai-theme-*` 变量，供自定义 Artifact 模板通过
 `ArtifactTemplateRenderContext.theme` 与 `themeStyle` 自行使用。语义成功/告警/错误色保持独立。
@@ -126,16 +125,14 @@ interface AssistantTransport {
 `regenerate` 存在时，面板才会展示成功回答的“重新生成”。该请求必须具备服务端替换旧回答或
 不追加重复用户消息的语义，不能简单映射到普通 `sendMessage`。`features` 决定 UI 是否展示
 新建会话、是否关闭重新生成，以及停止按钮应表达“远程取消”还是仅“停止接收”。默认会显示头部
-“新建对话”图标按钮，`features.newConversation === false` 时隐藏；点击新建对话会取消当前生成、
-清空本地会话，并调用可选的 `onNewConversation`。
+“新建对话”图标按钮，`features.newConversation === false` 时隐藏；Make App 新建对话调用持久创建；通用 transport 清理本地视图。两者均可调用 `onNewConversation`。
 历史快照最多接受 200 条消息、1,000,000 字符正文和 500 个 Artifact；同一条历史消息内
 Artifact id 必须唯一，避免恢复后产生重复渲染 key。
 
-传输边界支持中断。UI 在停止时会立即回到可输入状态、忽略迟到事件，并尝试关闭
-AsyncIterator，因此即使自定义 transport 没有及时响应 `AbortSignal`，也不会一直卡在
+传输边界支持中断。通用流 UI 在停止时释放输入并尝试关闭
+AsyncIterator；Make App 则等待独立取消命令的服务端终态，因此不会将连接关闭误记为取消。通用自定义 transport 没有及时响应 `AbortSignal` 时也不会一直卡在
 streaming。停止按钮会通过 hover/focus tooltip 展示“停止生成”或“停止接收”。关闭
-`MakeAiAssistant` 抽屉只隐藏 Drawer，不触发 active run cancel；取消只由停止、新建会话、
-切换 App/reinitialize 或根组件卸载触发。真实实现可以读取 fetch SSE，也可以把 AG-UI
+`MakeAiAssistant` 抽屉只隐藏 Drawer，不触发 active run cancel；新建、切换 App/身份或卸载只释放本地工作，Make App 远程取消只来自显式停止。真实实现可以读取 fetch SSE，也可以把 AG-UI
 runtime 事件归一化为包事件。
 UI 不直接请求固定 URL。
 
@@ -176,23 +173,19 @@ UI 会拒绝孤立、迟到、重复或跨 run 混入的事件，避免静默丢
 
 ## Make App transport
 
-`/make-app` 导出 `createMakeAppAssistantTransport`、
-`MakeAppAssistantTransportOptions`、`MakeAppAssistantEventSourceFactory` 及相关结构类型。
-宿主需要注入四个语义能力：
-
-- `locateChat(context, options)`：按当前宿主身份与 App 定位会话，返回 `chatId`；
-- `loadHistory({ chatId, cursor, limit }, options)`：恢复已定位会话的历史；
-- `sendMessage({ chatId, messageId, text }, options)`：提交幂等消息并返回 `responseId`；
-- `eventSourceFactory({ chatId, responseId, cursor }, init)`：订阅响应事件。
-
-每个异步回调都会收到可选 `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。
+`/make-app` 导出 `createMakeAppAssistantTransport`、`MakeAppAssistantTransportOptions`、`MakeAppAssistantScope`、`MakeAppAssistantEventSourceFactory` 及相关结构类型。完整回调与接线示例见 [当前 Make App 合同](docs/make-app-integration.md)。
+
+宿主注入 resolveScope 和 17 项语义能力：listAgents、createChat、listChats、getChat、updateChat、deleteChat、loadHistory、sendMessage、getResponse、cancelResponse、setFeedback、startUpload、getUpload、uploadPart、completeUpload、readContent、eventSourceFactory。JSON 回调返回裸对象；204 返回 void；下载返回 Uint8Array。
+
+`resolveScope(context)` 返回 appKey、agentId 和随登录身份变化的 identityKey。包只用于作用域绑定与缓存失效，服务器仍独立鉴权。每个异步回调接受 AbortSignal；包不提供部署 URL、不读 Cookie、不导入认证 SDK。
+
+`AssistantTransport` 原地增加 listAgents、listConversations、create/get/update/deleteConversation、get/cancelResponse、setFeedback、上传/内容方法与 watchResponse。方法在通用 interface 上可选，Make App adapter 实现全部。loadConversation options 可传 threadId/cursor，返回 nextCursor/hasMore；分页读取不会隐式创建 Chat。
+
+输入 message 可携带 parts；响应事件增加 response.accepted/state/output_item.added/output_text.delta/output_item.done/snapshot/reconciled/terminal。每个 Run、item 和 part 的身份独立，持久助手 messageId 用于反馈。`AssistantConversationState.responses` 保存响应集合；输入可以合并到同一 Run，不按调用次数伪造 Turn。
+
+features 增加 conversationManagement、feedback、attachments、modelInputKinds。Make App 的 newConversation/remoteCancellation 为 true，regeneration 为 false。historyLimit 范围 1—200；maxEventCharacters 默认 1,000,000；重连由 adapter 单独负责。完整快照属于覆盖，不能当新 delta。
+
+根入口导出 AssistantContentPart、AssistantMedia、AssistantChat、AssistantChatPage、AssistantAgent、AssistantFeedback、AssistantUpload、AssistantResponseSnapshot、AssistantResponseEvent 等类型，仍无 React/DOM File 依赖。文件读取与 Object URL 留在 React/宿主边界。
 
 ## Make Console transport
 

package/README.md

@@ -39,7 +39,7 @@ export function AppAssistant() {
 设置为 `bottom-left`、`bottom-right`、`top-left`、`top-right`、`left-center` 或 `right-center`；默认值为
 `bottom-right`。`launcher` 自定义渲染器自行负责位置。浮动入口首次打开后，关闭抽屉只隐藏 Drawer，不卸载 `AssistantPanel`，因此不会中断
 正在进行的生成；重新打开时会按用户关闭前的滚动意图恢复消息位置，空闲时聚焦输入框，生成中
-聚焦停止按钮。只有点击“停止生成”、新建对话、切换 App/reinitialize 或宿主卸载根组件时才会取消当前请求。
+聚焦停止按钮。切换会话、App/身份或卸载根组件只释放本地订阅。Make App 的显式停止通过独立取消命令等待服务端终态；关闭订阅不会取消后台 Run。
 
 标准位置确定锚点后，宿主可在 `MakeAiAssistant` 外层通过 CSS 变量微调偏移：
 `--make-ai-launcher-left`、`--make-ai-launcher-right`、`--make-ai-launcher-top`、
@@ -73,9 +73,8 @@ AI transport；进度和可重试错误会显示在对应的 AI 回合中。
 
 ## Theme integration
 
-`MakeAiAssistant`、`AssistantPanel` 和 `ArtifactRenderer` 都支持同一个 `theme` 属性。标题栏、内容背景、正文、通用边框和用户消息的默认色固定，
-不会因宿主主题色变化：标题栏与承载面为白色，内容区为 `#f7f9fc`，正文为 `#15233d`，用户发送消息为
-`#2f6df6` 蓝底白字。主题色只用于竖线、圆点、图标、输入框焦点、发送按钮和标签等强调元素；成功、告警和错误仍使用独立语义色。
+`MakeAiAssistant`、`AssistantPanel` 和 `ArtifactRenderer` 都支持同一个 `theme` 属性。标题栏、内容区背景与用户提问气泡默认跟随宿主主题色；输入承载面固定白色，正文、通用边框保持包内中性色。
+除标题栏、内容区背景与用户提问气泡外，主题色只用于竖线、圆点、图标、输入框焦点、发送按钮和标签等强调元素；成功、告警和错误仍使用独立语义色。Markdown 表格滚动条固定为中性灰，不跟随主题色。
 
 ```tsx
 import type { MakeAiTheme } from "@qfei-design/make-ai-assistant/react";
@@ -92,12 +91,12 @@ const hostTheme: MakeAiTheme = {
 `primary` 为必填项，`primaryHover` 与 `onPrimary` 可选；若主色偏浅，请传入具有足够对比度的
 `onPrimary`。内置 UI 的强调色优先级为 `theme` 属性 > `--make-ai-theme-primary`、
 `--make-ai-theme-primary-hover`、`--make-ai-theme-on-primary` > `--make-ai-accent` >
-宿主 `--make-color-primary` > 包内默认值。`background`、`surface`、`text` 等中性色字段为兼容保留，
+宿主 `--make-color-primary` > 包内默认值。`background` 会控制内容区基础背景；`surface`、`text` 等其余中性色字段为兼容保留，
 不会改变内置默认样式；它们仍会写入 `renderContext.themeStyle`，供自定义 Artifact 模板自行使用。
 
 桌面端抽屉默认宽度为 480px，且该初始宽度是用户拖拽时的最小宽度。最大宽度默认是 `min(1024px, 72vw)`，宿主可通过 `maxDrawerWidth` 传入像素值覆盖；小于最小宽度的配置会回退至最小宽度。鼠标移至抽屉左边缘的 12px 热区时才会显示 2px 主题色拖拽提示线（可通过 `--make-ai-drawer-resize-line` 覆盖），可向左拖宽；获得焦点后也可用左、右方向键以 16px 调整宽度。不大于 560px 的视口保持全宽展示，不显示拖拽手柄。
 
-面板使用容器查询而非页面视口响应宽度：回答区、结构化结果、代码块和 Markdown 表格会随抽屉可用宽度扩展；达到 760px 时，表格优先按可用宽度分列并换行，长段落和列表仍限制在 96ch 内以保障阅读性。窄容器中的 Markdown 表格保留横向滚动保护，并使用细窄、跟随主题色的滚动条。宿主可通过 `--make-ai-panel-gutter-wide` 覆盖扩展抽屉的内边距。
+面板使用容器查询而非页面视口响应宽度：回答区、结构化结果、代码块和 Markdown 表格会随抽屉可用宽度扩展；达到 760px 时，表格优先按可用宽度分列并换行，长段落和列表仍限制在 96ch 内以保障阅读性。窄容器中的 Markdown 表格保留横向滚动保护，并使用细窄的中性灰滚动条。宿主可通过 `--make-ai-panel-gutter-wide` 覆盖扩展抽屉的内边距。
 
 成功的 AI 回答会显示仅含图标的复制按钮，鼠标悬浮或键盘聚焦时显示“复制”提示，按钮保留
 “复制回答”的无障碍名称；复制只处理该回答的文本内容，失败时会在本地 UI 内提示，不会把回答正文写入日志。AI 回答正文会按标题、
@@ -118,8 +117,7 @@ const hostTheme: MakeAiTheme = {
 宿主内容，传入 `[]` 时隐藏推荐问题。
 
 默认头部右侧会展示“新建对话”图标按钮；宿主将 `transport.features.newConversation` 显式设为
-`false` 时隐藏该按钮。点击新建对话会取消当前生成、清空本地会话，并调用可选的
-`onNewConversation` 回调。
+`false` 时隐藏该按钮。Make App 点击新建会持久创建 Chat，成功后切换会话；通用 transport 按其能力清理本地视图，并调用可选的 `onNewConversation` 回调。
 
 ## Package provides
 
@@ -195,33 +193,23 @@ const assistantTransport = createSseAssistantTransport({
 });
 ```
 
-已有 Make App AI Browser API 可使用专用 adapter：
+Make App 使用专用 adapter 与当前唯一公开契约：
 
 ```ts
 import { createMakeAppAssistantTransport } from "@qfei-design/make-ai-assistant/make-app";
 
 const assistantTransport = createMakeAppAssistantTransport({
-  locateChat: (context, options) =>
-    makeAppAiClient.locateChat(context, options),
-  loadHistory: (request, options) =>
-    makeAppAiClient.loadHistory(request, options),
-  sendMessage: (request, options) =>
-    makeAppAiClient.sendMessage(request, options),
-  eventSourceFactory: (subscription, init) =>
-    makeAppAiClient.subscribeResponse(subscription, init),
-  maxEventCharacters: 1_000_000,
+  ...makeAppAiClient,
+  resolveScope: () => ({ appKey, agentId, identityKey }),
+  modelInputKinds: ["text"],
 });
 ```
 
-该 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 字符，超限会在
-JSON 解析前被拒绝。
+`makeAppAiClient` 实现完整的 17 项语义回调：Agent/Chat 管理、分页历史、消息、响应快照、独立取消、反馈、上传/原件和 EventSource。完整类型与示例见 [Make App 接入说明](docs/make-app-integration.md) 和 [宿主示例](examples/make-app/main.tsx)。网络与认证由宿主注入，identityKey 随当前用户/租户变化。
+
+内置面板支持持久会话列表、新建、改名、置顶/删除、反馈与附件队列。历史 cursor=-1 从最早事件正向分页，空可见页仍可能存在后续事件。首次加载不隐式建会话，用户新建或主动发送才创建。item/part 增量、完整文本覆盖、快照恢复和持久 messageId 对账由包统一处理。
+
+停止显示“停止中”，直到服务端确认终态；中断订阅不取消后台 Run。当前 Make App 不提供重新生成语义，也不传 context/capabilities 或伪造 Artifact。modelInputKinds 默认只有 text，附件存储与模型理解分别验收。单条消息文本最多 8 KiB UTF-8，最多 32 个 parts。
 
 Make Console 可以使用独立 adapter：
 
@@ -256,8 +244,7 @@ Console BFF 与 Make App Browser API 是两个独立宿主协议，不应只替
 需要兼容已有事件协议时，在宿主内实现薄 adapter；不要修改聊天组件或复制 Artifact 模板。
 
 流必须以 `run.complete`、`run.cancelled` 或 `error` 终止；异常断流会进入可重试错误状态。
-停止生成按钮悬浮或键盘聚焦时会显示“停止生成”提示；点击后会立即解除输入锁定并丢弃迟到事件，
-标准 SSE transport 会同步取消底层 reader。关闭抽屉只隐藏 UI，不会触发该取消流程。
+停止生成按钮悬浮或键盘聚焦时会显示“停止生成”提示；Make App 点击后等待远程终态；标准 SSE transport 停止时取消底层 reader 并释放本地输入锁。关闭抽屉只隐藏 UI，不会触发该取消流程。
 `/sse` 的公开类型不依赖 TypeScript `DOM` lib，现代 Node 宿主也可直接消费。
 调用前已经取消的 `AbortSignal` 不会触发网络请求。
 助手只发送宿主提供的上下文，实际数据权限始终由宿主 Service 在服务端重新校验。

package/capabilities.json

@@ -9,7 +9,11 @@
       "status": "experimental",
       "summary": "Versioned semantic result contract, runtime validation and JSON Schema.",
       "docPath": "PUBLIC_API.md",
-      "relatedExports": ["validateArtifact", "parseArtifact", "MakeAiArtifact"]
+      "relatedExports": [
+        "validateArtifact",
+        "parseArtifact",
+        "MakeAiArtifact"
+      ]
     },
     {
       "id": "artifact-registry",
@@ -18,7 +22,11 @@
       "status": "experimental",
       "summary": "Deterministic template selection, extension and capability negotiation.",
       "docPath": "PUBLIC_API.md",
-      "relatedExports": ["createArtifactTemplateRegistry", "resolveArtifactTemplate", "createArtifactCapabilities"]
+      "relatedExports": [
+        "createArtifactTemplateRegistry",
+        "resolveArtifactTemplate",
+        "createArtifactCapabilities"
+      ]
     },
     {
       "id": "react-shell",
@@ -27,7 +35,10 @@
       "status": "experimental",
       "summary": "Floating launcher, right-side drawer, embedded panel and streaming conversation UI.",
       "docPath": "README.md",
-      "relatedExports": ["MakeAiAssistant", "AssistantPanel"]
+      "relatedExports": [
+        "MakeAiAssistant",
+        "AssistantPanel"
+      ]
     },
     {
       "id": "platform-templates",
@@ -36,7 +47,11 @@
       "status": "experimental",
       "summary": "Default metric, comparison, trend, ranking, record-list and notice renderers.",
       "docPath": "PUBLIC_API.md",
-      "relatedExports": ["ArtifactRenderer", "createPlatformArtifactRegistry", "platformArtifactTemplates"]
+      "relatedExports": [
+        "ArtifactRenderer",
+        "createPlatformArtifactRegistry",
+        "platformArtifactTemplates"
+      ]
     },
     {
       "id": "sse-transport",
@@ -45,16 +60,22 @@
       "status": "experimental",
       "summary": "Abortable fetch SSE adapter for the standard Make AI Assistant event contract.",
       "docPath": "PUBLIC_API.md",
-      "relatedExports": ["@qfei-design/make-ai-assistant/sse:createSseAssistantTransport", "AssistantTransport"]
+      "relatedExports": [
+        "@qfei-design/make-ai-assistant/sse:createSseAssistantTransport",
+        "AssistantTransport"
+      ]
     },
     {
       "id": "make-app-transport",
       "name": "Make App AI transport",
       "category": "integration",
       "status": "experimental",
-      "summary": "Host-injected adapter for durable Make App chats, history and response-level SSE events.",
+      "summary": "宿主注入的多会话管理、反馈、附件与 item/part SSE、快照恢复和远程取消。",
       "docPath": "PUBLIC_API.md",
-      "relatedExports": ["@qfei-design/make-ai-assistant/make-app:createMakeAppAssistantTransport", "AssistantTransport"]
+      "relatedExports": [
+        "@qfei-design/make-ai-assistant/make-app:createMakeAppAssistantTransport",
+        "AssistantTransport"
+      ]
     },
     {
       "id": "make-console-transport",
@@ -63,7 +84,10 @@
       "status": "experimental",
       "summary": "Host-injected adapter for Console Agents, Sessions, durable events, Run SSE and polling fallback.",
       "docPath": "PUBLIC_API.md",
-      "relatedExports": ["@qfei-design/make-ai-assistant/make-console:createMakeConsoleAssistantTransport", "AssistantTransport"]
+      "relatedExports": [
+        "@qfei-design/make-ai-assistant/make-console:createMakeConsoleAssistantTransport",
+        "AssistantTransport"
+      ]
     },
     {
       "id": "mock-transport",
@@ -72,7 +96,10 @@
       "status": "experimental",
       "summary": "Protocol-compatible mock transport and generic fixtures for App integration before backend readiness.",
       "docPath": "README.md",
-      "relatedExports": ["createMockAssistantTransport", "artifactFixtures"]
+      "relatedExports": [
+        "createMockAssistantTransport",
+        "artifactFixtures"
+      ]
     }
   ]
 }