@qfei-design/make-ai-assistant 0.2.16 → 0.3.1

package/dist/styles.css

@@ -385,15 +385,15 @@
 .make-ai-assistant__task-list-icon {
   display: block;
   flex: 0 0 auto;
-  height: 19px;
-  width: 19px;
+  height: 14px;
+  width: 14px;
 }
 
 .make-ai-assistant__task-list-disclosure {
   display: block;
   flex: 0 0 auto;
-  height: 15px;
-  width: 15px;
+  height: 14px;
+  width: 14px;
 }
 
 .make-ai-assistant__header-title {
@@ -635,6 +635,7 @@
   display: grid;
   font-size: var(--make-ai-internal-font-size-markdown);
   gap: var(--make-ai-internal-assistant-block-gap);
+  grid-template-columns: minmax(0, 1fr);
   line-height: var(--make-ai-internal-line-height-body);
   max-width: 100%;
   white-space: normal;
@@ -644,8 +645,7 @@
 .make-ai-assistant__assistant-text p,
 .make-ai-assistant__assistant-text .make-ai-assistant__markdown-heading,
 .make-ai-assistant__assistant-text ul,
-.make-ai-assistant__assistant-text .make-ai-assistant__markdown-table-scroll,
-.make-ai-assistant__assistant-text pre {
+.make-ai-assistant__assistant-text .make-ai-assistant__markdown-table-scroll {
   margin: 0;
 }
 
@@ -722,8 +722,11 @@
   color: var(--make-ai-internal-text-secondary);
   font-size: 1em;
   line-height: 1.55;
+  margin: 0;
   max-width: 100%;
-  overflow: auto;
+  min-width: 0;
+  overflow-x: auto;
+  overscroll-behavior-inline: contain;
   padding: 9px 10px;
 }
 
@@ -732,8 +735,15 @@
   border: 0;
   color: inherit;
   display: block;
+  overflow-wrap: normal;
   padding: 0;
   white-space: pre;
+  word-break: normal;
+}
+
+.make-ai-assistant__assistant-text pre:focus-visible {
+  outline: 2px solid var(--make-ai-internal-accent);
+  outline-offset: 2px;
 }
 
 .make-ai-assistant__markdown-table-scroll {
@@ -933,8 +943,7 @@
   display: flex;
   gap: 10px;
   list-style: none;
-  min-height: 48px;
-  padding: 10px 12px;
+  padding: 8px 12px;
 }
 
 .make-ai-assistant__process summary:hover {
@@ -999,25 +1008,29 @@
 }
 
 .make-ai-assistant__process-copy {
-  display: grid;
-  gap: 1px;
+  align-items: center;
+  display: flex;
+  gap: 8px;
   min-width: 0;
 }
 
 .make-ai-assistant__process-title {
   color: var(--make-ai-internal-text);
+  flex: 0 0 auto;
   font-size: var(--make-ai-internal-font-size-ui);
   font-weight: 700;
-  line-height: var(--make-ai-internal-line-height-ui);
+  line-height: var(--make-ai-internal-line-height-caption);
+  white-space: nowrap;
 }
 
 .make-ai-assistant__process .make-ai-assistant__process-latest {
   color: var(--make-ai-internal-text-secondary);
   display: block;
-  flex: 0 1 auto;
+  flex: 1 1 auto;
   font-size: var(--make-ai-internal-font-size-meta);
   line-height: var(--make-ai-internal-line-height-meta);
   min-height: 0;
+  min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
@@ -1042,7 +1055,11 @@
   gap: 8px;
   list-style: none;
   margin: 0;
-  padding: 11px 14px 13px;
+  padding: 8px 12px;
+}
+
+.make-ai-assistant__process > .make-ai-assistant__assistant-text {
+  padding: 8px 12px;
 }
 
 .make-ai-assistant__process li {

package/docs/make-app-integration.md

@@ -11,16 +11,34 @@ const client = createMakeAgentClient({
   scope: { appKey, identityKey },
   transport: authenticatedTransport,
 });
+// 先由宿主通过 client.agents.list() 读完分页，确定唯一的应用内 Agent。
 const assistantTransport = await createMakeAppAssistantTransport({ client, agentId });
 // 将 assistantTransport 传入 AssistantPanel / MakeAiAssistant。
 // App、用户或租户改变时，取消旧连接并 client.dispose()，重新创建实例。
 ```
 
+## 应用内 Agent
+
+一个应用只绑定一个应用内 Agent。宿主取得该 Agent 的 `agentId` 后，调用
+`createMakeAppAssistantTransport({ client, agentId })`，并把返回的 `transport` 传给
+`AssistantPanel` 或 `MakeAiAssistant`。包不提供 Agent 选择器，也不通过列表接口自行决定 Agent。
+如果宿主尚未取得 `agentId`，应先完成自己的加载或错误处理，再挂载对话组件；App、用户或租户
+变化时中止旧请求、释放旧 client 并创建新实例。`identityKey` 仅用于隔离客户端状态，不是授权凭据。
+模型选择与 Agent 绑定不同；当前组件尚无模型选择合同，不能用 Agent 列表代替模型列表。
+
+首次选取 Agent 必须由宿主调用 `client.agents.list()` 读取完整分页：
+`createMakeAppAssistantTransport()` 创建时就要求 `agentId`，因此不能先创建 transport 再用
+`transport.listAgents()` 做首次选取。两个列表方法都会保留可选的 `agentType`：已知值包括
+`app_internal`、`channel`，未来新增的字符串值也会透传；旧响应未提供时该属性缺失。
+SDK 不按类型筛选、不默认选中 Agent。需要应用内 Agent 的宿主应在读完分页后自行筛选
+`agentType === "app_internal"`，对零个或多个匹配项分别给出未配置或配置冲突提示，不能用其他
+类型顶替。选定后再用该 `agentId` 创建 transport；其他宿主可采用自己的选择规则。
+
 `AuthenticatedTransport.request` 只执行一次已认证 I/O，返回 status、headers 和 AsyncIterable<Uint8Array>。`retryOwner: "sdk"` 由 SDK 按幂等语义做有限重试；`retryOwner: "transport"` 不叠加 SDK 重试。宿主沿正式 auth.api 处理登录、401/403 和 Cookie，SSE/二进制成功体不经过 JSON 或 text() 缓冲。SDK 不读取 Token、Cookie、LocalStorage 或 Provider key。
 
 普通操作分组为 capabilities、agents、chats、messages、responses、feedback、uploads 和 content。所有分页 cursor 都是不透明字符串；末页 nextCursor 为空串。不要把 Session 事件序号或 Redis ID 拼进公开 cursor。消息 messageId、Chat requestId、Feedback requestId 和 Upload fileId 来自用户的一次真实意图；重试使用同一个 ID 和字节，不重新生成。
 
-SDK 忽略新增响应元数据，但验证已知字段及归属。未知可选 SSE 事件产生 kind=unknown；未知输出 part 产生安全占位类型，不能用于输入或自动执行业务动作。已知字段损坏、跨 Response 帧和同一 cursor 已知语义字段冲突的重放均报 AI_PROTOCOL_ERROR。Response 的未知 status 按 terminal 决定是否结束；snapshotRevision 阻止旧快照覆盖新状态。
+SDK 忽略其他新增响应元数据，但保留可选的 Agent `agentType`，并验证已知字段及归属。未知可选 SSE 事件产生 kind=unknown；未知输出 part 产生安全占位类型，不能用于输入或自动执行业务动作。已知字段损坏、跨 Response 帧和同一 cursor 已知语义字段冲突的重放均报 AI_PROTOCOL_ERROR。Response 的未知 status 按 terminal 决定是否结束；snapshotRevision 阻止旧快照覆盖新状态。
 
 Chat.titlePending 缺失按 false；已知待摘要会话每秒通过同一 client.chats.get 刷新，摘要完成即显示，与正文终态独立。取消只走 responses.cancel；关闭迭代器/组件只停止本地读取。
 
@@ -33,3 +51,40 @@ capabilities 返回可选 feature、当前 modelInputKinds 和 limits。适配
 chat.management 只控制改名、置顶和删除；缺失该可选 feature 时仍可创建、选择和读取会话。缺失 attachments.read 时不提供下载入口。
 
 发生游标重置或采用权威快照后，后续恢复继续读取有界快照直到终态，避免把没有共同游标的确认视图与旧增量混合。
+
+
+## 标准接入
+
+```ts
+import {
+  createMakeAgentClient,
+  type Scope,
+  type AuthenticatedTransport,
+} from '@qfei-design/make-ai-assistant/client';
+import { createMakeAppAssistantTransport } from '@qfei-design/make-ai-assistant/make-app';
+
+async function connectAssistant(
+  scope: Scope,
+  agentId: string,
+  transport: AuthenticatedTransport,
+  signal: AbortSignal,
+) {
+  const client = createMakeAgentClient({ scope, transport });
+  try {
+    const assistantTransport = await createMakeAppAssistantTransport({
+      client, agentId, signal,
+    });
+    return { transport: assistantTransport, dispose: () => client.dispose() };
+  } catch (error) {
+    client.dispose();
+    throw error;
+  }
+}
+```
+
+将返回的 transport 交给助手界面，在用户、租户、App 切换和宿主卸载时执行 dispose。适配器会读取 capabilities，因此工厂是异步函数。创建过程中传入 signal，防止身份切换后旧结果重新挂载。identityKey 只隔离客户端缓存，不能作为服务端授权凭据。
+
+AuthenticatedTransport 提供一次正式认证的 HTTP 请求及原始字节流，明确 retryOwner。它沿用 Make App Auth 的登录与续期流程，不读取浏览器 Token 或 Cookie，不对 SSE 做 JSON 解包。服务代理保留方法、查询、二进制、AbortSignal、原始响应以及版本和请求 ID 头，不再次实现客户端状态机。
+
+
+宿主只在正式身份可用后创建实例；初始化 signal 中止时不得把旧身份返回的 transport 挂到新页面。服务代理保留方法、查询、版本头、AbortSignal 与响应字节。

package/examples/make-app/README.md

@@ -1,11 +1,29 @@
 # Make App 接入示例
 
-本示例消费包的公开 `/react`、`/make-app` 和样式入口，展示 17 项语义回调如何连接宿主同源服务。所有 POC 复用包内会话、流式、反馈和上传状态，不复制其内部实现。
+本示例消费包公开的 `/client`、`/react`、`/make-app` 和样式入口，演示宿主如何为应用内唯一 Agent
+创建 transport 并挂载对话组件；不复制包内部的状态机。源代码按接入顺序阅读：
+
+1. [transport.ts](transport.ts)：由宿主注入已认证的同源 HTTP 字节流请求，并用 `agentId` 创建 transport。
+2. [main.tsx](main.tsx)：读取当前宿主配置并挂载 React 示例。
 
 先在仓库根目录执行 `corepack pnpm build`，再执行 `corepack pnpm make-app:build`。输出在本目录的 dist，仅供宿主服务托管或本地验收；本例不处理登录、不读取 Token，也不提供生产 BFF。
 
-宿主提供同源 `GET /runtime-config`，响应为 `{appKey, appName, agentId, identityKey}`；identityKey 是用户/租户变化时同步变化的非凭据缓存隔离键。该配置不构成服务器授权。生产 POC 应将示例 request 换成已有认证客户端，并沿现有 Service/Make Gateway 转发公共接口。
+宿主提供同源 `GET /runtime-config`，响应包含以下内容：
+
+```json
+{"appKey":"当前 App Key","appName":"当前 App 名称","agentId":"应用内 Agent ID","identityKey":"当前用户和租户的非凭据标识"}
+```
+
+`identityKey` 在用户/租户变化时必须随之变化；它只隔离客户端状态，不是授权依据。示例
+`transport.ts` 使用同源 `fetch` 展示请求形状，生产宿主应接入现有认证客户端及 Service/Make Gateway，
+沿正式登录与鉴权链路处理 401/403，并透传 `AbortSignal` 和响应字节流。不得将 Token 放入
+`/runtime-config`、`scopeKey`、日志或包内部。
+
+一个应用只绑定一个应用内 Agent；宿主须在挂载对话组件前取得对应 `agentId`，而不是让包显示
+Agent 选择器。App 或身份改变时应取消旧请求、释放旧 Client 并创建新实例，不能沿用旧会话。
+模型切换属于不同能力，当前示例不提供模型选择界面。
 
 当前 Make App 后端只支持文本模型输入；示例的 modelInputKinds 为 `["text"]`，但仍保留统一的“上传文件或图片”入口。服务端必须根据消息 parts 和实际模型能力校验媒体类型；不要以原件存储或读取能力判断模型已经支持输入。
 
-详见 [接入说明](../../docs/make-app-integration.md)。正式发布仍由原仓库 GitLab CI 负责。
+完整属性、transport 功能门控见 [公共 API](../../PUBLIC_API.md#组件参数速查)；更多协议与安全约束见
+[接入说明](../../docs/make-app-integration.md)。正式发布仍由原仓库 GitLab CI 负责。

package/package.ai.json

@@ -1,6 +1,6 @@
 {
   "packageName": "@qfei-design/make-ai-assistant",
-  "minimumRuntimeVersion": "0.2.16",
+  "minimumRuntimeVersion": "0.3.1",
   "readOrder": [
     "package.ai.json",
     "README.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qfei-design/make-ai-assistant",
-  "version": "0.2.16",
+  "version": "0.3.1",
   "description": "Platform-wide Make AI Assistant contracts, React shell, and context-aware artifact templates.",
   "type": "module",
   "sideEffects": [