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

package/dist/sse.cjs

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const b=require("./conversation-Cv1wdvCR.cjs"),S=1e6,u=e=>typeof e=="object"&&e!==null&&!Array.isArray(e),p=(e,t,r)=>{const a=Object.keys(e).find(s=>s.toLowerCase()===t.toLowerCase());a&&delete e[a],e[t]=r},A=e=>{const t={};return Array.isArray(e)?e.forEach(([r,a])=>p(t,r,a)):e&&typeof e.forEach=="function"?e.forEach((r,a)=>p(t,a,r)):e&&Object.entries(e).forEach(([r,a])=>p(t,r,a)),p(t,"Accept","text/event-stream"),p(t,"Content-Type","application/json"),t},I=(e,t)=>{if(!u(t))throw new Error("Invalid assistant SSE event: data");if(Object.prototype.hasOwnProperty.call(t,"type"))throw new Error("Invalid assistant SSE event: unsupported field");try{return b.parseAssistantEvent({...t,type:e})}catch(r){throw r instanceof Error&&r.message.startsWith("Invalid assistant event")?new Error(r.message.replace("Invalid assistant event","Invalid assistant SSE event")):r}},w=e=>{if(!e.trim())return;const t=e.split(`
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const b=require("./conversation-Cvh-IVRV.cjs"),S=1e6,u=e=>typeof e=="object"&&e!==null&&!Array.isArray(e),p=(e,t,r)=>{const a=Object.keys(e).find(s=>s.toLowerCase()===t.toLowerCase());a&&delete e[a],e[t]=r},A=e=>{const t={};return Array.isArray(e)?e.forEach(([r,a])=>p(t,r,a)):e&&typeof e.forEach=="function"?e.forEach((r,a)=>p(t,a,r)):e&&Object.entries(e).forEach(([r,a])=>p(t,r,a)),p(t,"Accept","text/event-stream"),p(t,"Content-Type","application/json"),t},I=(e,t)=>{if(!u(t))throw new Error("Invalid assistant SSE event: data");if(Object.prototype.hasOwnProperty.call(t,"type"))throw new Error("Invalid assistant SSE event: unsupported field");try{return b.parseAssistantEvent({...t,type:e})}catch(r){throw r instanceof Error&&r.message.startsWith("Invalid assistant event")?new Error(r.message.replace("Invalid assistant event","Invalid assistant SSE event")):r}},w=e=>{if(!e.trim())return;const t=e.split(`
 `),r=t.find(n=>n.startsWith("event:"))?.slice(6).trim(),a=t.filter(n=>n.startsWith("data:")).map(n=>n.slice(5).trimStart()).join(`
 `);if(t.some(n=>n.startsWith("event:")||n.startsWith("data:"))){if(!r||!a)throw new Error("Invalid assistant SSE event: missing event or data");try{return I(r,JSON.parse(a))}catch(n){throw n instanceof Error&&n.message.startsWith("Invalid assistant SSE event")?n:new Error("Invalid assistant SSE event: JSON")}}};async function*T(e,t,r=S){if(!e.body)throw new Error("当前运行环境无法读取 AI 助手流式响应");const a=e.body.getReader(),s=new TextDecoder;let n="",d=!1,h=!1,l;const c=()=>(l??=a.cancel().catch(o=>{console.error("[make-ai-assistant] SSE reader cancellation failed",{errorType:o instanceof Error?o.name:typeof o})}),l),f=()=>{c()};t?.addEventListener("abort",f,{once:!0});const m=o=>{const i=o.type==="error"||o.type==="run.cancelled"||o.type==="run.complete";return h||=i,i};try{for(;;){if(t?.aborted)throw new DOMException("Aborted","AbortError");const o=await a.read();if(t?.aborted)throw new DOMException("Aborted","AbortError");let i=s.decode(o.value,{stream:!o.done});d&&(i=`\r${i}`,d=!1),!o.done&&i.endsWith("\r")&&(i=i.slice(0,-1),d=!0),o.done&&d&&(i+="\r",d=!1),n+=i.replace(/\r\n|\r/g,`
 `);let E=n.indexOf(`

package/dist/sse.mjs

@@ -1,4 +1,4 @@
-import { p as b } from "./conversation-B7eGUXi-.js";
+import { l as b } from "./conversation-CZfbgCXd.js";
 const S = 1e6, u = (e) => typeof e == "object" && e !== null && !Array.isArray(e), E = (e, t, r) => {
   const a = Object.keys(e).find(
     (s) => s.toLowerCase() === t.toLowerCase()

package/dist/styles.css

@@ -3,14 +3,14 @@
   --make-ai-internal-accent-strong: var(--make-ai-theme-primary-hover, var(--make-ai-accent-strong, var(--make-color-primary-hover, color-mix(in srgb, var(--make-ai-internal-accent) 84%, var(--make-ai-internal-text)))));
   --make-ai-internal-on-accent: var(--make-ai-theme-on-primary, var(--make-ai-on-accent, #fcfcff));
   --make-ai-internal-accent-soft: var(--make-ai-accent-soft, color-mix(in srgb, var(--make-ai-internal-accent) 10%, var(--make-ai-internal-bg)));
-  --make-ai-internal-bg: #f7f9fc;
+  --make-ai-internal-bg: var(--make-ai-theme-bg, var(--make-ai-bg, var(--make-color-bg, color-mix(in srgb, var(--make-ai-internal-accent) 2%, #fcfcff))));
   --make-ai-internal-surface: #fff;
   --make-ai-internal-surface-strong: #f1f4f9;
   --make-ai-internal-text: #15233d;
   --make-ai-internal-text-secondary: #738096;
   --make-ai-internal-border: #dbe3ef;
-  --make-ai-internal-user-message-bg: #2f6df6;
-  --make-ai-internal-user-message-text: #fff;
+  --make-ai-internal-scrollbar-thumb: #9aa0a8;
+  --make-ai-internal-scrollbar-thumb-hover: #7b8490;
   --make-ai-internal-success: var(--make-ai-success, var(--make-color-success, #1a9a61));
   --make-ai-internal-warning: var(--make-ai-warning, var(--make-color-warning, #c77b00));
   --make-ai-internal-danger: var(--make-ai-danger, var(--make-color-danger, #d04444));
@@ -280,7 +280,7 @@
 
 .make-ai-assistant__header {
   align-items: center;
-  background: var(--make-ai-internal-surface);
+  background: var(--make-ai-internal-bg);
   border-bottom: 1px solid var(--make-ai-internal-border);
   display: grid;
   gap: 8px;
@@ -682,10 +682,10 @@
 }
 
 .make-ai-assistant__message--user .make-ai-assistant__bubble {
-  background: var(--make-ai-internal-user-message-bg);
-  border: 1px solid var(--make-ai-internal-user-message-bg);
+  background: color-mix(in srgb, var(--make-ai-internal-accent) 4%, var(--make-ai-internal-bg));
+  border: 1px solid color-mix(in srgb, var(--make-ai-internal-accent) 7%, var(--make-ai-internal-border));
   border-radius: 16px 5px 16px 16px;
-  color: var(--make-ai-internal-user-message-text);
+  color: color-mix(in srgb, var(--make-ai-internal-text) 82%, var(--make-ai-internal-accent));
   font-size: var(--make-ai-internal-font-size-heading);
   line-height: var(--make-ai-internal-line-height-heading);
   padding: 10px 13px;
@@ -803,7 +803,7 @@
   max-width: 100%;
   overflow-x: auto;
   overscroll-behavior-inline: contain;
-  scrollbar-color: color-mix(in srgb, var(--make-ai-internal-accent) 46%, var(--make-ai-internal-border)) transparent;
+  scrollbar-color: var(--make-ai-internal-scrollbar-thumb) transparent;
   scrollbar-width: thin;
 }
 
@@ -817,7 +817,7 @@
 }
 
 .make-ai-assistant__markdown-table-scroll::-webkit-scrollbar-thumb {
-  background: color-mix(in srgb, var(--make-ai-internal-accent) 46%, var(--make-ai-internal-border));
+  background: var(--make-ai-internal-scrollbar-thumb);
   background-clip: padding-box;
   border: 1px solid transparent;
   border-radius: 999px;
@@ -825,7 +825,7 @@
 
 .make-ai-assistant__markdown-table-scroll:hover::-webkit-scrollbar-thumb,
 .make-ai-assistant__markdown-table-scroll:focus-within::-webkit-scrollbar-thumb {
-  background: color-mix(in srgb, var(--make-ai-internal-accent) 64%, var(--make-ai-internal-border));
+  background: var(--make-ai-internal-scrollbar-thumb-hover);
 }
 
 .make-ai-assistant__markdown-table {
@@ -1738,6 +1738,57 @@ button.make-ai-artifact__record:hover { background: var(--make-ai-internal-accen
   }
 }
 
+.make-ai-assistant__conversation-controls {
+  border-bottom: 1px solid var(--make-ai-internal-border);
+  flex: 0 0 auto;
+  font-size: var(--make-ai-internal-font-size-meta);
+  max-height: 240px;
+  overflow: auto;
+  padding: 8px 12px;
+}
+.make-ai-assistant__panel--managed { grid-template-rows: auto auto minmax(0, 1fr) auto; }
+.make-ai-assistant__panel--managed > .make-ai-assistant__conversation-controls { grid-row: 2; }
+.make-ai-assistant__panel--managed > .make-ai-assistant__body { grid-row: 3; }
+.make-ai-assistant__panel--managed > .make-ai-assistant__composer-region { grid-row: 4; }
+.make-ai-assistant__response-status { color: var(--make-ai-internal-text-secondary); font-size: var(--make-ai-internal-font-size-meta); }
+
+.make-ai-assistant__conversation-list { max-height: 130px; overflow: auto; }
+.make-ai-assistant__conversation-row { display: flex; gap: 4px; margin-bottom: 4px; }
+.make-ai-assistant__conversation-row > button:first-child { flex: 1; min-width: 0; overflow: hidden; text-align: left; text-overflow: ellipsis; white-space: nowrap; }
+.make-ai-assistant__conversation-row > button[aria-pressed="true"] { background: var(--make-ai-internal-accent-soft); color: var(--make-ai-internal-accent); }
+.make-ai-assistant__conversation-actions { align-items: center; display: flex; flex-wrap: wrap; gap: 6px; padding-top: 8px; }
+.make-ai-assistant__conversation-actions input { flex: 1; min-width: 100px; }
+.make-ai-assistant__conversation-controls button,
+.make-ai-assistant__feedback button,
+.make-ai-assistant__attachment button,
+.make-ai-assistant__attachment-composer button {
+  background: var(--make-ai-internal-surface);
+  border: 1px solid var(--make-ai-internal-border);
+  border-radius: 6px;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  padding: 4px 8px;
+}
+.make-ai-assistant__feedback { display: flex; flex-wrap: wrap; gap: 6px; font-size: var(--make-ai-internal-font-size-meta); }
+.make-ai-assistant__feedback button[aria-pressed="true"] { color: var(--make-ai-internal-accent); border-color: var(--make-ai-internal-accent); }
+.make-ai-assistant__feedback form { display: grid; flex-basis: 100%; gap: 6px; }
+.make-ai-assistant__feedback input,
+.make-ai-assistant__feedback textarea,
+.make-ai-assistant__conversation-actions input { border: 1px solid var(--make-ai-internal-border); border-radius: 6px; color: inherit; font: inherit; padding: 6px; width: 100%; }
+.make-ai-assistant__attachment { align-items: center; display: flex; flex-wrap: wrap; gap: 6px; padding: 8px; border: 1px solid var(--make-ai-internal-border); border-radius: 8px; font-size: var(--make-ai-internal-font-size-meta); }
+.make-ai-assistant__attachment img,
+.make-ai-assistant__attachment video { max-height: 260px; max-width: 100%; object-fit: contain; }
+.make-ai-assistant__attachment audio { max-width: 100%; }
+.make-ai-assistant__attachment-composer { font-size: var(--make-ai-internal-font-size-meta); max-height: 140px; overflow: auto; padding-bottom: 8px; }
+.make-ai-assistant__attachment-composer input { max-width: 100%; }
+.make-ai-assistant__attachment-composer ul { list-style: none; margin: 6px 0 0; padding: 0; }
+.make-ai-assistant__attachment-composer li { align-items: center; display: flex; flex-wrap: wrap; gap: 4px; padding: 4px 0; }
+.make-ai-assistant__conversation-controls button:focus-visible,
+.make-ai-assistant__feedback button:focus-visible,
+.make-ai-assistant__attachment button:focus-visible,
+.make-ai-assistant__attachment-composer button:focus-visible { outline: 2px solid var(--make-ai-internal-accent); outline-offset: 2px; }
+
 @media (prefers-reduced-motion: reduce) {
   .make-ai-assistant__drawer,
   .make-ai-assistant__launcher-orbit,

package/docs/backend-contract.md

@@ -1,4 +1,4 @@
-# Make AI 助手后端 V1 配合合同
+# Make AI 助手后端配合合同
 
 ## Make Console 当前 Web 接口
 
@@ -26,28 +26,15 @@ Console BFF 与 Make App Browser API 的认证和资源模型不同，不能只
 transport。平台包分别提供 `/make-console` 与 `/make-app` 两个入口，聊天 UI 与 Artifact
 模板保持共享。
 
-## Make App 现有后端接入
+## Make App 当前后端接入
 
-Make App 内嵌助手可以通过 `/make-app` adapter 对接宿主已有的 Browser API。npm 包只定义
-下列语义操作，不定义或拼接任何部署路径：
+Make App 通过 `/make-app` adapter 消费当前唯一契约。包提供 Chat 管理、历史、输入、输出、反馈、上传和原件的语义方法，实际 URL/身份与代理由宿主负责。完整接口映射与时序见 [接入说明](make-app-integration.md)。
 
-| 语义操作 | 输入 | 输出 |
-| --- | --- | --- |
-| 定位会话 | 当前 `MakeAssistantHostContext` | `{ chatId }` |
-| 加载历史 | `{ chatId, cursor: -1, limit }` | `{ messages }` |
-| 提交消息 | `{ chatId, messageId, text }` | `{ chatId, responseId, acceptedCursor }` |
-| 订阅响应 | `{ chatId, responseId, cursor }` | 兼容 adapter 合同的 EventSource |
-
-实际请求由宿主认证边界发起。URL、请求方法、Cookie、Ingress、Service 代理、租户与当前用户
-解析都由宿主决定；浏览器不能读取或构造服务端凭证。宿主必须传递 `AbortSignal`，并在取消
-后尽快停止尚未完成的请求。
-
-当前事件包括 `run.started`、`response.delta`、`response.progress`、
-`response.message`、`response.completed`、`response.failed` 和 `heartbeat`。
-`response.message` 是完整文本替换，不是 delta。当前接口没有新建会话、远程取消和
-Artifact；前端必须按能力降级，不应伪造这些能力。
-Make App adapter 会在 `JSON.parse` 前限制单个 EventSource `data` 字符数，默认
-1,000,000；历史恢复最多接受 200 条消息、1,000,000 字符正文和 500 个 Artifact。
+宿主返回裸 JSON，204 没有 body，内容读取返回 Uint8Array。Chat 的 title/pinned 修改和删除使用 expectedRevision；创建和反馈使用稳定 requestId；发送使用稳定 messageId。历史从数值 cursor 正向读取，列表使用独立不透明游标。
+
+SSE 使用 response.subscribed/state、output_item.added/output_text.delta/output_item.done、reset/snapshot 以及 completed/failed/cancelled。输出项身份与最终持久消息身份分离；生成完成后读历史对账，再提交反馈。快照覆盖已有视图；关闭订阅不会取消 Run，显式取消可能先返回 202，随后确认终态。
+
+附件先完成分段上传，引用 ready 内容的长度/MIME/摘要后发送。模型媒体能力逐类验收，不能凭上传成功开放。当前 Make App 没有 Artifact 或重新生成的服务器语义，不发送未定义的 context/capabilities 扩展。
 
 ## 通用标准接口能力
 

package/docs/make-app-integration.md

@@ -0,0 +1,80 @@
+# Make App 当前契约接入
+
+本分支将现有 `/make-app` 入口原地接入当前个人多会话、反馈、附件和 item/part SSE 契约。没有协议版本选择，没有隐式定位单一会话，也不自动替宿主做登录。包版本发布号与业务协议无关。
+
+## 宿主接线
+
+从 `@qfei-design/make-ai-assistant/make-app` 导入 `createMakeAppAssistantTransport`，从 `/react` 导入 `MakeAiAssistant` 或 `AssistantPanel`。实现下面的语义回调；可复制 [宿主回调映射](../examples/make-app/transport.ts) 中的映射，替换为 POC 已有认证请求封装。所有 URL、Cookie 转发与服务端鉴权属于宿主。
+
+| 宿主回调 | 作用与结果 |
+|---|---|
+| resolveScope(context) | 返回明确的 appKey、agentId、identityKey；用户或租户变化时 identityKey 必须改变 |
+| listAgents | 产品内启用 Agent 数组的裸响应 |
+| createChat | requestId 幂等创建；返回 Chat |
+| listChats | 当前用户在产品/Agent 下的列表；返回 chats、nextCursor、hasMore |
+| getChat / updateChat / deleteChat | 详情、title/pinned 更新、软删除；更新/删除带 expectedRevision |
+| loadHistory | 指定 chatId 和数值 cursor；返回 messages、nextCursor、hasMore |
+| sendMessage | 稳定 messageId；text 或 parts 二选一；返回 chatId、responseId、acceptedCursor |
+| getResponse / cancelResponse | 权威快照、独立取消；取消可能返回仍 running 的快照与 cancelRequested=true |
+| setFeedback | 持久助手 messageId、requestId、like/dislike/none，以及可选 reason/comment |
+| startUpload / getUpload | 上传初始化与 completedParts 续传进度 |
+| uploadPart / completeUpload | 从 0 编号的二进制分段，全部完成后获取 ready 内容引用 |
+| readContent | 鉴权后原始 Uint8Array，不能把 contentRef 当公开 URL |
+| eventSourceFactory | 以 chatId、responseId、cursor 创建带凭据的 EventSource；包负责关闭与重连 |
+
+JSON 回调返回服务端裸对象，204 返回 void，内容返回 Uint8Array。不要在所有响应上统一解包 data 或 JSON.parse。每个异步回调都必须传递 AbortSignal。scopeKey 仅隔离浏览器内的状态，不能代替服务器授权。
+
+会话查询和创建相互独立。`loadConversation(context,{threadId,cursor,signal})` 只恢复选中的会话，不隐式创建；UI 点击新建或首次主动发送才创建。公开返回的 `threadId` 对应 chatId，responseId 对应执行 Run。
+
+## 包提供的交互
+
+内置面板可列出、选择、新建会话，编辑标题、置顶/取消置顶、确认删除；改名/置顶/删除失败保留用户可见错误。修订冲突后读取最新详情，不自动换 revision 覆盖。
+
+输入和重试保存稳定 UUID。多个输入可能对应同一 responseId；面板控制器在响应维度保持一个订阅，关闭面板继续保留当前 UI，切会话/身份或卸载只释放本地连接。停止按钮调用 cancelResponse，并等待终态；完成与取消竞争时接受服务端最终结果。
+
+输出按 itemId/partId 归并，完整 done 文本覆盖增量。中间模型活动放在过程区域，不能充当最终可反馈消息。response.completed 后读取历史对账，切换到持久助手 messageId，再开放反馈。点踩说明提交失败保留表单，重新提交复用未知结果的原意图；撤销用 rating=none。
+
+文件选择、拖拽和粘贴进入同一上传队列。分段大小读 partSize，重试先查 completedParts；未 ready 的附件不能发送。暂停/移除只影响本地任务和草稿，当前没有远程上传取消接口。附件卡片可鉴权下载和受控预览，不执行 HTML/SVG/脚本。
+
+## 流式事件与恢复
+
+公开流消费 `response.subscribed/state/output_item.added/output_text.delta/output_item.done/reset/snapshot/completed/failed/cancelled`。这些事件在 adapter 转换为 headless 的响应事件，不复用通用 SSE 的消息身份来猜最终答案。
+
+公开 `AssistantEvent` 增加：
+
+- response.accepted：输入受理与 responseId 关联。
+- response.state、response.output_item.added、response.output_text.delta、response.output_item.done：运行状态和项级输出。
+- response.snapshot：覆盖该响应已确认的输出视图。
+- response.reconciled：持久消息对账。
+- response.terminal：completed/failed/cancelled 终态。
+
+`AssistantConversationState.responses` 保存各响应状态，activeRunId 只是当前活动响应的便利字段，不是唯一运行事实。终态后迟到增量不能重新打开响应。原有通用 SSE、Console、Mock 与 Artifact 公共入口仍各自归一化到同一 headless 合同。
+
+EventSource.onerror 后先关闭旧实例，再由 adapter 从最后处理游标有界重连；不要同时设置第二套宿主重连循环。query cursor 优先于 Last-Event-ID。reset 后消费服务器快照；通道连续失败时切到权威快照。快照没有完整在途 token，也没有可直接切回 Redis 的水位，不能将任意旧 delta 追加到快照。
+
+完成对账失败会报告恢复错误，不能被重连逻辑吞掉。普通断网与 HTTP/SSE 读取失败都不等同于业务 Run 已取消。
+
+## 限制与未开放能力
+
+| 事项 | 当前行为 |
+|---|---|
+| 输入 | 文本累计 8 KiB UTF-8；最多 32 个有序 parts；整体消息 JSON 64 KiB |
+| 上传 | 单文件 64 MiB，分段当前 1 MiB；服务端按完整 Namespace 限流/限容量 |
+| 历史 | cursor=-1 从最早事件正向扫描，limit 数底层事件；空可见页仍可 hasMore=true |
+| 长历史 | 分页继续加载，有界展示最近加载的 200 条/正文预算；不会声称首个窗口是全部历史 |
+| 模型媒体能力 | modelInputKinds 默认只有 text；逐类真实模型验收后由宿主开放 |
+| 未完成上传 | 服务端当前 24 小时失效；无公开 abort/清理，容量不保证自动回收 |
+| 下载 | 当前为 attachment/octet-stream，不承诺 Range/206；预览用本地受控 Blob |
+| Artifact/页面上下文 | 通用能力保留；当前 Make App 请求不携带 context/capabilities，不从 Markdown 猜 Artifact |
+| 重新生成 | 没有服务端替换语义，保持关闭；普通再次提问属于新消息 |
+
+后端模型媒体适配未启用时，内部 LLM 可能返回 unsupported_media；公开消息先受理为 202 后再以 AI_RUN_FAILED 终止。前端不能依赖消息 POST 直接返回 422。
+
+## 后续 POC 接手
+
+1. 对接现有统一登录和 Service，完成所有语义回调；认证过期、产品/Agent/用户切换都重新核对。
+2. 由宿主决定当前选中会话的 URL/持久化导航、草稿体验、Agent 入口和主题布局。刷新后可从包的列表选择历史会话恢复。
+3. 用真实宿主验证未缓冲 SSE、断网重连、取消、修订冲突、反馈回显和附件字节；本地示例不是已部署 POC。
+4. 经接手人检查后，按现有 GitLab CI 发布 alpha，再升级 POC 依赖。当前用户要求只交 feature 分支，本轮不发包、不部署 Dev。
+
+完整字段说明以 agent-design 的 MakeAppProtocol/OpenAPI 与接口手册为准；交接飞书文档同时提供 17 项 HTTP 清单、请求示例、分支和本地验收结果。

package/examples/make-app/README.md

@@ -0,0 +1,11 @@
+# Make App 接入示例
+
+本示例消费包的公开 `/react`、`/make-app` 和样式入口，展示 17 项语义回调如何连接宿主同源服务。所有 POC 复用包内会话、流式、反馈和上传状态，不复制其内部实现。
+
+先在仓库根目录执行 `corepack pnpm build`，再执行 `corepack pnpm make-app:build`。输出在本目录的 dist，仅供宿主服务托管或本地验收；本例不处理登录、不读取 Token，也不提供生产 BFF。
+
+宿主提供同源 `GET /runtime-config`，响应为 `{appKey, appName, agentId, identityKey}`；identityKey 是用户/租户变化时同步变化的非凭据缓存隔离键。该配置不构成服务器授权。生产 POC 应将示例 request 换成已有认证客户端，并沿现有 Service/Make Gateway 转发公共接口。
+
+当前 Make App 后端只支持文本模型输入；示例的 modelInputKinds 为 `["text"]`。图片、文件、非实时音视频可先上传和查看原件，模型理解逐类验收后再配置开放。不要以文件上传成功判断模型已经支持。
+
+详见 [接入说明](../../docs/make-app-integration.md)。正式发布仍由原仓库 GitLab CI 负责。

package/examples/make-app/index.html

@@ -0,0 +1,5 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width, initial-scale=1.0" /><title>Make App 助手接入验收</title></head>
+  <body><div id="root"></div><script type="module" src="/main.tsx"></script></body>
+</html>

package/examples/make-app/main.tsx

@@ -0,0 +1,34 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { AssistantPanel } from "@qfei-design/make-ai-assistant/react";
+import { createHostTransport, type Configuration } from "./transport";
+import "@qfei-design/make-ai-assistant/styles.css";
+import "./style.css";
+
+const config: Configuration = await fetch("/runtime-config").then((response) =>
+  response.json(),
+);
+if (
+  ![config.appKey, config.agentId, config.identityKey].every(
+    (value) => typeof value === "string" && value.length > 0,
+  )
+)
+  throw new Error("缺少宿主产品、Agent 或身份配置");
+const transport = createHostTransport(config);
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <main className="example-shell">
+      <p className="example-notice">本地接入验收 · 使用宿主配置的真实后端</p>
+      <AssistantPanel
+        context={{
+          app: { id: config.appKey, name: config.appName },
+          location: { pathname: "/" },
+          locale: "zh-CN",
+          timezone: "Asia/Shanghai",
+        }}
+        transport={transport}
+        suggestions={[]}
+      />
+    </main>
+  </StrictMode>,
+);

package/examples/make-app/style.css

@@ -0,0 +1,4 @@
+body { margin: 0; background: #f4f6f9; font-family: system-ui, sans-serif; }
+.example-shell { margin: 20px auto; max-width: 880px; padding: 0 12px; }
+.example-notice { color: #617086; font-size: 12px; }
+.example-shell .make-ai-assistant__panel { background: white; border: 1px solid #dbe3ef; border-radius: 12px; height: calc(100dvh - 85px); min-height: 420px; }

package/examples/make-app/transport.ts

@@ -0,0 +1,163 @@
+import {
+  createMakeAppAssistantTransport,
+  type MakeAppAssistantEventSource,
+  type MakeAppAssistantEventSourceEvent,
+} from "@qfei-design/make-ai-assistant/make-app";
+export interface Configuration {
+  appKey: string;
+  appName: string;
+  agentId: string;
+  identityKey: string;
+}
+
+export function createHostTransport(
+  config: Configuration,
+  fetcher: typeof fetch = fetch,
+) {
+  const prefix = "/api/make/app/ai";
+  const id = encodeURIComponent;
+  const query = (values: Record<string, string | number | undefined>) =>
+    new URLSearchParams(
+      Object.entries(values)
+        .filter(
+          (entry): entry is [string, string | number] => entry[1] !== undefined,
+        )
+        .map(([key, value]) => [key, String(value)]),
+    ).toString();
+  const request = async (
+    path: string,
+    init: RequestInit = {},
+    binary = false,
+  ) => {
+    // 替换为 POC 已有的认证请求封装；本示例同样只访问宿主同源接口。
+    const response = await fetcher(prefix + path, {
+      credentials: "include",
+      ...init,
+    });
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw Object.assign(new Error("请求未完成"), {
+        status: response.status,
+        code: body.code,
+      });
+    }
+    if (response.status === 204) return undefined;
+    return binary
+      ? new Uint8Array(await response.arrayBuffer())
+      : response.json();
+  };
+  const json = (
+    method: string,
+    body: unknown,
+    signal?: AbortSignal,
+  ): RequestInit => ({
+    method,
+    signal,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return createMakeAppAssistantTransport({
+    resolveScope: () => ({
+      appKey: config.appKey,
+      agentId: config.agentId,
+      identityKey: config.identityKey,
+    }),
+    listAgents: (input, options) => request(`/agents?${query(input)}`, options),
+    listChats: (input, options) => request(`/chats?${query(input)}`, options),
+    createChat: (input, options) =>
+      request("/chats", json("POST", input, options.signal)),
+    getChat: ({ chatId }, options) => request(`/chats/${id(chatId)}`, options),
+    updateChat: ({ chatId, ...body }, options) =>
+      request(`/chats/${id(chatId)}`, json("PATCH", body, options.signal)),
+    deleteChat: async ({ chatId, expectedRevision }, options) => {
+      await request(`/chats/${id(chatId)}?${query({ expectedRevision })}`, {
+        method: "DELETE",
+        signal: options.signal,
+      });
+    },
+    loadHistory: ({ chatId, ...page }, options) =>
+      request(`/chats/${id(chatId)}/messages?${query(page)}`, options),
+    sendMessage: ({ chatId, ...body }, options) =>
+      request(
+        `/chats/${id(chatId)}/messages`,
+        json("POST", body, options.signal),
+      ),
+    getResponse: ({ chatId, responseId }, options) =>
+      request(`/chats/${id(chatId)}/responses/${id(responseId)}`, options),
+    cancelResponse: ({ chatId, responseId }, options) =>
+      request(
+        `/chats/${id(chatId)}/responses/${id(responseId)}/cancel`,
+        json("POST", {}, options.signal),
+      ),
+    setFeedback: ({ chatId, messageId, ...body }, options) =>
+      request(
+        `/chats/${id(chatId)}/messages/${id(messageId)}/feedback`,
+        json("PUT", body, options.signal),
+      ),
+    startUpload: ({ chatId, ...body }, options) =>
+      request(
+        `/chats/${id(chatId)}/uploads`,
+        json("POST", body, options.signal),
+      ),
+    getUpload: ({ chatId, uploadId }, options) =>
+      request(`/chats/${id(chatId)}/uploads/${id(uploadId)}`, options),
+    uploadPart: async ({ chatId, uploadId, part, bytes }, options) => {
+      await request(
+        `/chats/${id(chatId)}/uploads/${id(uploadId)}/parts/${part}`,
+        {
+          method: "PUT",
+          signal: options.signal,
+          headers: { "Content-Type": "application/octet-stream" },
+          body: new Uint8Array(bytes).buffer,
+        },
+      );
+    },
+    completeUpload: ({ chatId, uploadId }, options) =>
+      request(
+        `/chats/${id(chatId)}/uploads/${id(uploadId)}/complete`,
+        json("POST", {}, options.signal),
+      ),
+    readContent: async ({ chatId, contentRef }, options) =>
+      request(`/chats/${id(chatId)}/content/${id(contentRef)}`, options, true),
+    eventSourceFactory: ({ chatId, responseId, cursor }, init) => {
+      const source = new EventSource(
+        `${prefix}/chats/${id(chatId)}/events?${query({ responseId, cursor })}`,
+        init,
+      );
+      type Listener = (event: MakeAppAssistantEventSourceEvent) => void;
+      const listeners = new Map<string, Map<Listener, EventListener>>();
+      const wrapped: MakeAppAssistantEventSource = {
+        get readyState() {
+          return source.readyState;
+        },
+        onerror: null,
+        addEventListener(type, listener) {
+          const receive: EventListener = (event) => {
+            const message = event as MessageEvent<unknown>;
+            if (typeof message.data === "string")
+              listener({
+                data: message.data,
+                lastEventId: message.lastEventId,
+              });
+          };
+          const group = listeners.get(type) ?? new Map();
+          group.set(listener, receive);
+          listeners.set(type, group);
+          source.addEventListener(type, receive);
+        },
+        removeEventListener(type, listener) {
+          const receive = listeners.get(type)?.get(listener);
+          if (receive) source.removeEventListener(type, receive);
+          listeners.get(type)?.delete(listener);
+        },
+        close() {
+          source.close();
+        },
+      };
+      source.onerror = (event) => wrapped.onerror?.(event);
+      return wrapped;
+    },
+    // 按实际模型验收开放类型；上传存储能力与模型理解能力独立。
+    modelInputKinds: ["text"],
+  });
+}

package/examples/make-app/vite.config.ts

@@ -0,0 +1,7 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+export default defineConfig({
+  root: "examples/make-app",
+  plugins: [react()],
+  build: { outDir: "dist", emptyOutDir: true },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qfei-design/make-ai-assistant",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Platform-wide Make AI Assistant contracts, React shell, and context-aware artifact templates.",
   "type": "module",
   "sideEffects": [
@@ -55,13 +55,21 @@
     "recipes.json",
     "capabilities.json",
     "docs/artifact-v1.md",
-    "docs/backend-contract.md"
+    "docs/backend-contract.md",
+    "docs/make-app-integration.md",
+    "examples/make-app/main.tsx",
+    "examples/make-app/style.css",
+    "examples/make-app/README.md",
+    "examples/make-app/vite.config.ts",
+    "examples/make-app/index.html",
+    "examples/make-app/transport.ts"
   ],
   "scripts": {
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly && node scripts/copy-styles.mjs && node scripts/smoke-dist.mjs",
     "gallery:build": "vite build --config examples/gallery/vite.config.ts",
+    "make-app:build": "vite build --config examples/make-app/vite.config.ts",
     "sprint:init": "qfei-release sprint-init",
     "release:init": "qfei-release release-init",
     "publish:alpha": "qfei-release publish --channel alpha",

package/recipes.json

@@ -14,7 +14,10 @@
         "AssistantTransport",
         "ArtifactActionHandler"
       ],
-      "readNext": ["README.md", "PUBLIC_API.md"],
+      "readNext": [
+        "README.md",
+        "PUBLIC_API.md"
+      ],
       "commonMistakes": [
         "Calling Make API directly from the UI",
         "Passing Make tokens through the package",
@@ -32,7 +35,10 @@
         "Service endpoint",
         "Optional credentials and request headers"
       ],
-      "readNext": ["README.md", "docs/backend-contract.md"],
+      "readNext": [
+        "README.md",
+        "docs/backend-contract.md"
+      ],
       "commonMistakes": [
         "Importing the SSE implementation from the headless root",
         "Sending Make tokens from the browser",
@@ -41,20 +47,27 @@
     },
     {
       "id": "make-app-browser-api",
-      "summary": "Connect the assistant to the existing Make App AI Browser API.",
+      "summary": "接入当前 Make App 多会话、反馈、类型化附件和 item/part SSE 合同。",
       "use": [
         "@qfei-design/make-ai-assistant/make-app:createMakeAppAssistantTransport"
       ],
       "hostProvides": [
-        "Authenticated semantic callbacks for chat lookup, history and message submission",
-        "Credentialed response EventSource factory",
-        "Current Make App context"
+        "明确 appKey/agentId/identityKey 的 resolveScope",
+        "17 项已认证语义回调及带凭据的 EventSource 工厂",
+        "实际模型已验收的 modelInputKinds"
+      ],
+      "readNext": [
+        "README.md",
+        "PUBLIC_API.md",
+        "docs/backend-contract.md",
+        "docs/make-app-integration.md"
       ],
-      "readNext": ["README.md", "PUBLIC_API.md", "docs/backend-contract.md"],
       "commonMistakes": [
-        "Creating or forwarding service credentials in browser code",
-        "Treating response.message as a text delta",
-        "Showing new-chat or remote-cancel controls when the backend does not support them"
+        "浏览器读写服务凭据",
+        "将 itemId 当作持久反馈 messageId",
+        "用关闭连接冒充远程取消",
+        "忽略空历史页的 hasMore",
+        "把上传成功视为模型理解成功"
       ]
     },
     {
@@ -68,7 +81,11 @@
         "Credentialed Run EventSource factory",
         "Current Make Console App context"
       ],
-      "readNext": ["README.md", "PUBLIC_API.md", "docs/backend-contract.md"],
+      "readNext": [
+        "README.md",
+        "PUBLIC_API.md",
+        "docs/backend-contract.md"
+      ],
       "commonMistakes": [
         "Reading or copying zs_session in application code",
         "Treating SSE as the durable source of truth",
@@ -88,7 +105,10 @@
         "canRender predicate based on Artifact semantics and host context",
         "Accessible React presentation"
       ],
-      "readNext": ["README.md", "PUBLIC_API.md"],
+      "readNext": [
+        "README.md",
+        "PUBLIC_API.md"
+      ],
       "commonMistakes": [
         "Registering a business-specific template as a platform default",
         "Using a backend component name as an executable import path",
@@ -106,7 +126,10 @@
         "App context",
         "Optional request-specific mock response"
       ],
-      "readNext": ["README.md", "PUBLIC_API.md"],
+      "readNext": [
+        "README.md",
+        "PUBLIC_API.md"
+      ],
       "commonMistakes": [
         "Building a second mock-only component path",
         "Putting POC business fixtures into platform default templates",