@qfei-design/make-ai-assistant 0.1.0 → 0.1.3

package/PUBLIC_API.md

@@ -5,6 +5,8 @@
 - `@qfei-design/make-ai-assistant`：headless Artifact、会话、模板注册和 transport 合同。
 - `@qfei-design/make-ai-assistant/react`：React 助手壳、ArtifactRenderer 和平台模板。
 - `@qfei-design/make-ai-assistant/sse`：基于 Fetch、ReadableStream 的浏览器/现代 Node SSE transport；公开声明不要求 TypeScript `DOM` lib。
+- `@qfei-design/make-ai-assistant/make-app`：Make App AI 语义协议 adapter；网络请求、认证和 EventSource 创建均由宿主注入。
+- `@qfei-design/make-ai-assistant/make-console`：Make Console Agent/Session/Run 语义协议 adapter；认证请求和 EventSource 创建由 Console 宿主注入。
 - `@qfei-design/make-ai-assistant/testing`：Mock transport 和通用 fixtures，仅用于开发、测试与 Gallery。
 - `@qfei-design/make-ai-assistant/styles.css`：助手壳与默认模板样式。
 - `@qfei-design/make-ai-assistant/artifact-v1.schema.json`：服务端与工具使用的机器可读 Schema。
@@ -34,8 +36,10 @@ Fetch SSE 实现时，从 `/sse` 入口导入 `createSseAssistantTransport`。
 
 ## React exports
 
-- `MakeAiAssistant`：默认浮动入口与右侧抽屉；支持受控开关和自定义 launcher。
-- `AssistantPanel`：不带 Drawer 的嵌入式会话面板。
+- `MakeAiAssistant`：默认浮动入口与右侧抽屉；支持受控开关、自定义 launcher，以及
+  `assistantName` / `userName` 对双方消息显示名称的覆盖。
+- `AssistantPanel`：不带 Drawer 的嵌入式会话面板；支持 `assistantName` / `userName`，
+  默认显示“AI 助手”和“你”。
 - `ArtifactRenderer`：注册表驱动的单 Artifact 渲染器。
 - `createPlatformArtifactRegistry`
 - `platformArtifactTemplates`
@@ -53,6 +57,15 @@ Promise rejection。`onActionError` 自身同步抛错或返回 rejected Promise
 
 ```ts
 interface AssistantTransport {
+  readonly features?: Partial<{
+    history: boolean;
+    newConversation: boolean;
+    remoteCancellation: boolean;
+  }>;
+  loadConversation?(
+    context: MakeAssistantHostContext,
+    options?: { signal?: AbortSignal },
+  ): Promise<AssistantConversationSnapshot>;
   run(
     request: AssistantRunRequest,
     options?: { signal?: AbortSignal },
@@ -60,6 +73,11 @@ interface AssistantTransport {
 }
 ```
 
+`loadConversation` 存在时，面板会先进入初始化状态并恢复历史；失败时展示可重试状态。
+`features` 决定 UI 是否展示新建会话，以及停止按钮应表达“远程取消”还是仅“停止接收”。
+历史快照最多接受 200 条消息、1,000,000 字符正文和 500 个 Artifact；同一条历史消息内
+Artifact id 必须唯一，避免恢复后产生重复渲染 key。
+
 传输边界支持中断。UI 在停止时会立即回到可输入状态、忽略迟到事件，并尝试关闭
 AsyncIterator，因此即使自定义 transport 没有及时响应 `AbortSignal`，也不会一直卡在
 streaming。真实实现可以读取 fetch SSE，也可以把 AG-UI runtime 事件归一化为包事件。
@@ -75,10 +93,10 @@ SSE 流必须以 `run.complete`、`run.cancelled` 或 `error` 结束。连接在
 被视为可重试的 transport 错误，避免 UI 永久停留在 streaming 状态。终止事件、解析
 失败、超限、Abort 和消费者提前结束都会取消并释放 response reader。
 
-用户输入与单次响应文本默认各限制为 100,000 字符。Artifact 的集合、字符串、JSON
-深度/节点/累计文本和校验问题数量也有固定预算；超限输入会被拒绝，不会继续遍历或
-进入 React 模板。React UI 会在消费任意 `AssistantTransport` 时再次调用
-`parseArtifact`，自定义 transport 也不能绕过运行时白名单。
+用户输入与单次响应文本默认各限制为 100,000 字符，历史正文总预算默认 1,000,000
+字符。Artifact 的集合、字符串、JSON 深度/节点/累计文本和校验问题数量也有固定预算；
+超限输入或历史快照会被拒绝，不会继续遍历或进入 React 模板。React UI 会在消费任意
+`AssistantTransport` 时再次调用 `parseArtifact`，自定义 transport 也不能绕过运行时白名单。
 
 自定义 transport 抛出的任意异常不会直接展示给用户；UI 只展示包自身的可控校验/
 限制消息或通用“连接失败，请重试”，完整内部错误应由宿主在 transport 边界记录。
@@ -95,6 +113,49 @@ UI 会拒绝孤立、迟到、重复或跨 run 混入的事件，避免静默丢
 所有 transport 事件在进入 UI 前都会由 headless `parseAssistantEvent` 检查事件类型、
 字段白名单、必填值、identifier 长度与 Artifact；宿主 adapter 也可以直接复用该函数。
 
+`message.replace` 用于服务端发送完整响应快照并替换已累积文本；`run.progress` 用于展示
+“正在查询记录”等过程状态，不写入最终消息正文。二者都受统一文本预算和事件顺序校验。
+
+## 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；在后端加入版本化结构结果前，
+真实链路只渲染文本和进度。
+`historyLimit` 可配置为 1 到 100；`maxEventCharacters` 控制单个 EventSource `data` 的
+最大字符数，默认 1,000,000，超限会在 `JSON.parse` 前终止本次流并关闭 EventSource。
+
+## Make Console transport
+
+`/make-console` 导出 `createMakeConsoleAssistantTransport`、
+`MakeConsoleAssistantTransportOptions`、`MakeConsoleAgentSummary`、
+`MakeConsoleAssistantEventSourceFactory` 及相关结构类型。宿主注入五个语义能力：
+
+- `listAgents({ appKey }, options)`：读取当前 App 的 Agent 列表；
+- `getOrCreateSession({ appKey, agentID }, options)`：幂等创建或复用当前登录人的 Console Session；
+- `loadEvents({ appKey, agentID, sessionID, from, limit }, options)`：读取 PostgreSQL 持久事件；
+- `sendMessage({ appKey, agentID, text }, options)`：发送消息并返回 `sessionID`、`seq`、`runID/mergedInto`；
+- `eventSourceFactory({ appKey, agentID, sessionID, runID, cursor }, init)`：订阅 Run 实时输出。
+
+adapter 默认选择第一个启用的 Agent，也允许宿主用 `selectAgent` 在已启用列表中选择。
+`run-output/output_text.delta` 会追加到当前消息；`response.completed` 后会从 `seq + 1`
+读取持久事件，用完整 Agent 消息替换增量文本。`fallback` 和无 effective Run ID 场景使用
+同一持久事件轮询路径。持久事件是最终事实源，SSE 只用于实时体验。
+
+该入口不拼接 `/api/make/console/v1` URL、不访问 Cookie，也不导入认证 SDK。Console 宿主
+必须通过已有认证请求边界解包普通响应的 `data`，并创建 `withCredentials: true` 的
+EventSource。输入上限为 4000 个 Unicode 字符；历史最多读取 200 条，SSE 单事件默认上限
+为 1,000,000 字符。
+
 ## Host responsibilities
 
 Host app provides context, transport, action execution, permission checks, Service routes, authentication and routing. The package provides the presentation runtime and contracts, but does not access Make API and does not execute server-generated HTML.

package/README.md

@@ -5,7 +5,7 @@
 ## Install
 
 ```bash
-pnpm add @qfei-design/make-ai-assistant@^0.1.0
+pnpm add @qfei-design/make-ai-assistant@^0.1.2
 ```
 
 ## Quick start
@@ -34,12 +34,17 @@ export function AppAssistant() {
 
 `MakeAiAssistant` 默认渲染右下角动效入口和右侧抽屉。宿主可以使用 `open` / `onOpenChange` 受控管理开关，也可以用 `AssistantPanel` 嵌入自己的容器。
 
+默认会话会以“你”和“AI 助手”区分双方消息。宿主可以通过 `userName` 与
+`assistantName` 覆盖这两个显示名称；进度和可重试错误会显示在对应的 AI 回合中。
+
 ## Package provides
 
 - Artifact V1 类型、运行时校验与 JSON Schema；
 - Artifact 模板注册、能力协商和稳定降级；
 - 纯会话 reducer 与 `AssistantTransport` 合同；
 - `/sse` 入口提供可直接配置 endpoint 的 `createSseAssistantTransport`；
+- `/make-app` 入口提供现有 Make App AI 会话、历史消息和 SSE 事件的协议适配器；
+- `/make-console` 入口提供 Console Agent、Session、持久事件和 Run SSE 的协议适配器；
 - `MakeAiAssistant`、`AssistantPanel` 和 `ArtifactRenderer`；
 - metric、comparison、trend、ranking、record-list、notice 六类默认模板；
 - Mock transport 与 Gallery fixtures；
@@ -48,14 +53,14 @@ export function AppAssistant() {
 ## Host app provides
 
 - 当前 App、路径、Entity/Record/View 等最小上下文；
-- 实现 `AssistantTransport` 的 Mock、SSE 或 AG-UI 适配器；
+- 实现 `AssistantTransport`，或向 `/make-app`、`/make-console` 适配器注入已认证的语义请求和事件订阅能力；
 - Artifact 动作到宿主路由、命令与权限检查的映射；
 - Service `/api`、认证、数据查询、模型运行和服务端权限校验；
 - 可选的 App 领域模板和主题变量。
 
-The package does not access Make API, does not hold or forward Make tokens, and does not execute server-generated HTML, JSX, CSS, or JavaScript.
+包自身不导入 Make 认证 SDK、不持有或透传 Make token，也不执行服务端生成的 HTML、JSX、CSS 或 JavaScript。`/make-app` 与 `/make-console` 只负责协议归一化，所有网络 I/O 均由宿主注入。
 
-React/ReactDOM 是 UI 入口的可选 peer dependency；只使用根入口、`/sse` 或 `/testing`
+React/ReactDOM 是 UI 入口的可选 peer dependency；只使用根入口、`/sse`、`/make-app`、`/make-console` 或 `/testing`
 的 Service/Node 工具不需要安装 React。
 
 只使用 `AssistantPanel` 做嵌入式接入，或单独使用 `ArtifactRenderer` 时，同一个
@@ -104,6 +109,61 @@ const assistantTransport = createSseAssistantTransport({
 });
 ```
 
+已有 Make App AI Browser API 可使用专用 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,
+});
+```
+
+该 adapter 会按 App 定位持久会话、加载最近历史、提交消息，并把
+`response.delta/progress/message/completed/failed` 归一化为包内事件。当前后端不提供
+新建会话与远程取消，因此 UI 会隐藏“新建对话”，停止操作只关闭本地 EventSource。
+具体 URL、认证方式、租户和当前用户解析全部由宿主实现；adapter 不缓存跨调用会话定位结果。
+Make App 历史恢复同样受包级预算保护：最多 200 条历史消息、1,000,000 字符历史正文和
+500 个历史 Artifact；单个 EventSource `data` 默认不能超过 1,000,000 字符，超限会在
+JSON 解析前被拒绝。
+
+Make Console 可以使用独立 adapter：
+
+```ts
+import { createMakeConsoleAssistantTransport } from "@qfei-design/make-ai-assistant/make-console";
+
+const assistantTransport = createMakeConsoleAssistantTransport({
+  listAgents: (request, options) =>
+    makeConsoleAiClient.listAgents(request, options),
+  getOrCreateSession: (request, options) =>
+    makeConsoleAiClient.getOrCreateSession(request, options),
+  loadEvents: (request, options) =>
+    makeConsoleAiClient.loadEvents(request, options),
+  sendMessage: (request, options) =>
+    makeConsoleAiClient.sendMessage(request, options),
+  eventSourceFactory: (subscription, init) =>
+    makeConsoleAiClient.subscribeRun(subscription, init),
+});
+```
+
+该 adapter 默认选择第一个 `status=enabled` 的 Agent；多个 Agent 场景可通过 `selectAgent`
+按宿主上下文选择。它会幂等定位当前用户 Session、从持久事件恢复历史、把
+`output_text.delta` 归一化为文本增量，并在 `response.completed` 后读取持久事件完成最终
+对账。收到 `fallback` 或发送结果没有可订阅 Run 时，会从用户消息 `seq + 1` 开始轮询持久
+事件。Console 输入按后端合同限制为 4000 个 Unicode 字符。
+
+Console 宿主负责把这些语义回调映射到 `/api/make/console/v1`，并通过现有登录体系使用
+`credentials: "include"` / `withCredentials: true`。包不会读取、写入或复制 `zs_session`。
+Console BFF 与 Make App Browser API 是两个独立宿主协议，不应只替换 URL 强行复用。
+
 需要兼容已有事件协议时，在宿主内实现薄 adapter；不要修改聊天组件或复制 Artifact 模板。
 
 流必须以 `run.complete`、`run.cancelled` 或 `error` 终止；异常断流会进入可重试错误状态。

package/capabilities.json

@@ -47,6 +47,24 @@
       "docPath": "PUBLIC_API.md",
       "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.",
+      "docPath": "PUBLIC_API.md",
+      "relatedExports": ["@qfei-design/make-ai-assistant/make-app:createMakeAppAssistantTransport", "AssistantTransport"]
+    },
+    {
+      "id": "make-console-transport",
+      "name": "Make Console AI transport",
+      "category": "integration",
+      "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"]
+    },
     {
       "id": "mock-transport",
       "name": "Testing adapter",