super-agent-sdk 1.0.9 → 1.0.11

package/README.md

@@ -35,6 +35,7 @@ Super Agent Web SDK —— 为 `super-agent-service` 提供的一站式浏览器
 - **嵌入式组件**：`mount()` 挂载 React 聊天组件。
 - **两种展示模式**：`floating`（右下角气泡 + 弹窗面板）与 `fullpage`（整页 DeepSeek 风格布局）。
 - **会话持久化**：自动加载会话列表、`localStorage` 记住最近会话、刷新后自动恢复。
+- **附件上传（NOS 直传）**：内置 NOS 直传（分片 + 断点续传 + 进度），📎 选文件随消息发送，沙箱 Agent 可读取文件内容（详见 [5.12](#512-createnosuploader) / [6.1](#61-mount)）。
 
 ---
 
@@ -183,6 +184,8 @@ const sessionId = await sdk.createSession();
 export interface ChatOptions {
   sessionId: string; // 必填 — 先调用 createSession()
   message: string;
+  /** 附件（≤10 个，仅沙箱模式 Agent 支持，其他模式后端返回 400）。需先经直传上传到 NOS 拿到 nosKey。 */
+  attachments?: ChatAttachment[];
   stream?: boolean; // 默认 true
   onMessage?: (event: ChatEvent) => void;
   onError?: (error: Error) => void;
@@ -193,6 +196,26 @@ export interface ChatOptions {
   }) => void; // messageId：后端在 done 事件返回的消息标识（存在时 SDK Widget 用其启用消息反馈，若返回可据此判断该消息可 feedback）
   signal?: AbortSignal;
 }
+
+export interface ChatAttachment {
+  nosKey: string; // NOS 对象 key（必填，直传后获得）
+  filename: string; // 原始文件名（必填，模型靠扩展名选择解析方式）
+  size?: number; // 字节数（后端落地时校验）
+  mime?: string; // MIME 类型，如 "application/pdf"
+  url?: string; // 下载链接（仅前端回显；发送时 SDK 自动剥离，不进后端）
+}
+```
+
+带附件发送（附件文件会由后端写入沙箱，Agent 可通过 `read_file` / `execute` 读取）：
+
+```ts
+const attachment = await createNosUploader({ baseURL: "/api/e5s" })(file); // 见 5.12
+const controller = sdk.chat({
+  sessionId,
+  message: "总结这份报告",
+  attachments: [attachment],
+  onMessage, onDone, onError,
+});
 ```
 
 ```ts
@@ -369,7 +392,33 @@ const skills: SkillInfo[] = await sdk.listSkills();
 // [{ code: "web-searcher", name: "web-searcher", displayName: "网页搜索", description: "..." }]
 ```
 
-### 5.12 后端接口对照
+### 5.12 createNosUploader()
+
+内置 NOS 直传上传器（协议对齐 `@netease-ehr/ui` Upload 的 nosUpload 路径，**零依赖**该私有包）：`nosKey = MD5(name:size:ts)` → `GET {baseURL}/nos/token` → nos-js-sdk 分片直传 NOS 边缘节点（默认 4MB 分片 + localStorage 断点续传）→ `GET {baseURL}/nos/url` 取下载地址。内置挂起防护（分片超时 120s + 无进度看门狗 130s）。
+
+```ts
+import { createNosUploader } from "super-agent-sdk";
+
+export interface NosUploaderConfig {
+  baseURL: string; // 业务网关（与业务系统接口网关一致，如 "/api/e5s"，同源相对路径）
+  headers?: Record<string, string>; // 网关鉴权头（token/url 两个 GET 携带）
+  trunkSize?: number; // 分片大小，默认 4MB
+  onProgress?: (percent: number) => void; // 上传进度 0-100
+  chunkTimeoutMs?: number; // 单分片超时，默认 120s
+  stallTimeoutMs?: number; // 无进度看门狗，默认 130s
+  fetchNosUrl?: boolean; // 上传后调 /nos/url 取下载地址，默认 true（失败降级不影响结果）
+}
+
+const upload = createNosUploader({
+  baseURL: "/api/e5s",
+  onProgress: (p) => console.log(`${p}%`),
+});
+const attachment = await upload(file); // → { nosKey, filename, size, mime, url }
+```
+
+> Widget 场景无需手动调用——`mount({ nosUpload: { baseURL } })` 一行开启（见 [6.1](#61-mount)）。
+
+### 5.13 后端接口对照
 
 SDK 方法 → 后端接口的完整映射：
 
@@ -379,7 +428,7 @@ SDK 方法 → 后端接口的完整映射：
 | --------------------- | -------------------------------------------- | --------------------------------------- | ----------------------------------------------- |
 | `getToken()`          | `POST {gateway}/v1/token`                    | `{ botId }`                             | `{ token, appId }`                              |
 | `createSession()`     | `POST /chat/sessions`                        | `{ botId }`                             | `{ sessionId }`                                 |
-| `chat()`              | `POST /chat`                                 | `{ botId, sessionId, message, stream }` | SSE 流，`done`/`stop` 事件含 `sessionId`        |
+| `chat()`              | `POST /chat`                                 | `{ botId, sessionId, message, stream, attachments? }` | SSE 流，`done`/`stop` 事件含 `sessionId`        |
 | `listConversations()` | `GET /chat/conversations`                    | 查询参数 `botId`、`page`、`size`        | `{ items: [{ sessionId, botId, ... }], total }` |
 | `feedback()`          | `POST /chat/messages/{messageId}/feedback`   | `{ type, reason?, remark? }`            | `null`                                          |
 | `cancelFeedback()`    | `DELETE /chat/messages/{messageId}/feedback` | 无 body                                 | `null`                                          |
@@ -418,6 +467,10 @@ export interface MountOptions {
   logo?: string; // floating 首页居中 Logo（URL），默认 SDK 内置 Logo
   triggerLogo?: string; // floating 触发按钮 Logo（URL），默认 SDK 内置 Logo
   showTimestamp?: boolean; // 显示消息时间戳，默认 false 不显示
+  /** 附件上传器（完全自定义，优先于 nosUpload）。不配置则输入区无附件按钮。 */
+  attachmentUploader?: (file: File) => Promise<ChatAttachment>;
+  /** 内置 NOS 直传（推荐）：配置即用，📎 按钮 + chip 进度 + 断点续传全内置 */
+  nosUpload?: { baseURL: string; headers?: Record<string, string>; trunkSize?: number };
 }
 
 export interface CapabilityItem {
@@ -430,7 +483,8 @@ export interface QuickLinkItem {
   icon?: string; // 图标 URL
   label: string; // 入口名称
   prompt?: string; // 点击后发送的消息
-  onClick?: () => void; // 自定义点击行为（优先于 prompt）
+  action?: PanelAction; // 点击行为：整屏容器 / 外链（优先于 prompt）
+  onClick?: () => void; // 自定义点击行为（优先于 action / prompt）
 }
 
 export interface WidgetInstance {
@@ -465,6 +519,31 @@ widget.destroy(); // 卸载并移除 DOM
 
 > 挂载后默认是收起状态，需调用 `widget.open()` 展开。
 
+#### 附件上传（📎 按钮）
+
+配置 `nosUpload`（内置 NOS 直传）或 `attachmentUploader`（完全自定义，优先级更高）任一即启用，二者都不配则附件功能完全隐藏（存量接入零影响）：
+
+```ts
+// 内置直传（推荐，一行开启）
+mount("#chat-root", {
+  sdk,
+  nosUpload: { baseURL: "/api/e5s" }, // 业务网关
+});
+
+// 完全自定义（其他对象存储 / 自建网关）
+mount("#chat-root", {
+  sdk,
+  attachmentUploader: async (file) => ({
+    nosKey: await uploadSomewhere(file),
+    filename: file.name,
+    size: file.size,
+    mime: file.type,
+  }),
+});
+```
+
+内置行为：📎 选文件（≤10 个）→ chip 实时显示上传百分比 → 上传完成显示文件大小（可点击下载）→ 随消息发送 → 沙箱 Agent 读取（仅沙箱模式 Agent 支持，其他模式后端 400）。上传中禁止发送，失败 chip 红标可移除重选；regenerate 会连同附件一起重发。
+
 ### 6.2 源码接入（monorepo alias）注意事项
 
 Widget 内部使用 **Tailwind CSS**（utility 全部限定在 `[data-super-agent-widget]` 宿主选择器内、禁用 preflight，不影响宿主页样式）。分发包（`dist`）已内联全部样式；内置图片资产（Logo/图标/头像等）走 CDN 绝对路径（`src/widget/assets/index.ts` 的 `BASE_URL`），**npm 引入无需任何配置**（需能访问 CDN）。
@@ -513,10 +592,10 @@ mount("#chat-root", { sdk, mode: "fullpage", sidebarDefaultOpen: false });
 浮窗窗口对齐 hr-for-help 设计，开箱具备以下交互能力：
 
 - **标题栏拖拽**：按住顶部导航栏移动窗口（视口内钳制，按钮区域不触发）
-- **左右拉伸调宽**：窗口左右两侧 6px 手柄拖拽，宽度范围 360 ~ 800 px，拖超过 800 自动进入大窗
+- **左侧拉伸调宽**：窗口左侧 6px 手柄拖拽（右缘稳定不动），宽度范围 360 ~ 800 px，拖超过 800 自动进入大窗
 - **大窗/小窗切换**：header 右侧「大窗」按钮切换；大窗为底部弹出的近全屏 overlay（内容区 800px 居中），回小窗时宽度重置为默认值
 - **内容自适应高度**：聊天内容增长时窗口自动变高（默认 648px，上限 95% 视口，超出后消息区滚动），回到首页恢复默认高度
-- **内嵌会话侧边栏**：header「历史记录」按钮开合；小窗展开时窗口自动加宽 200px；大窗模式自动展开（220px），大窗/小窗各自记住用户偏好
+- **内嵌会话侧边栏**：header「历史记录」按钮开合；小窗下侧边栏紧贴窗口左缘向外展开（无缝拼接为一个连续圆角窗口，主区位置不动）；大窗模式自动展开（220px），大窗/小窗各自记住用户偏好
 - **关闭即还原**：关闭窗口后几何状态（位置/宽度/大窗态/高度）全部重置
 
 浮窗消息展示对齐 hr-for-help：AI 头像独占一行（无背景色，生成中切换动效头像）、气泡白底描边、用户气泡浅蓝右对齐；`fullpage` 模式保持横排头像 + 经典气泡，两者互不影响。
@@ -610,6 +689,8 @@ export interface Slots {
   ErrorPart?: ComponentType<ErrorPartProps>;
   InterruptCard?: ComponentType<InterruptCardProps>;
   WelcomeScreen?: ComponentType<WelcomeScreenProps>;
+  /** 首屏底部业务定制容器 */
+  AppendContainer?: ComponentType<AppendContainerProps>;
 }
 ```
 
@@ -627,6 +708,7 @@ export interface Slots {
 | `ToolResultPart` | `ToolResultPartProps` | 工具返回卡片（pre 滚动 + 复制；`renderMode==="html"` 时 DOMPurify 清洗后直接渲染，最高 60vh 滚动） |
 | `ErrorPart`      | `ErrorPartProps`      | 错误提示块                                                                                         |
 | `WelcomeScreen`  | `WelcomeScreenProps`  | 空会话欢迎页                                                                                       |
+| `AppendContainer`| `AppendContainerProps`| 首屏底部业务定制区，`openPanel(action)` 开整屏容器或外链（见下）                                   |
 
 #### Trigger
 
@@ -774,7 +856,7 @@ function MyMessage({
 ```ts
 export interface ComposerProps {
   status: ChatStatus;
-  onSend: (content: string) => void;
+  onSend: (content: string, attachments?: ChatAttachment[]) => void;
   onStop: () => void;
 }
 ```
@@ -965,6 +1047,86 @@ function MyErrorPart({ content, onRetry }: ErrorPartProps) {
 }
 ```
 
+#### AppendContainer（首屏业务定制 + 整屏容器）
+
+首屏（无消息时）在 `WelcomeScreen` 之下预留一块业务定制区，浮窗与全屏模式共用；未配置则不产生任何 DOM。
+用法就一句话：**点一下，`openPanel(action)`**——可视区始终在 chatPanel 内（`link` 除外）。
+
+```ts
+export type PanelContent = ComponentType<PageProps> | ReactElement; // 组件类型，或带参数的元素
+export type PanelAction =
+  | { type: 'page'; component: PanelContent; title?: string } // 整屏容器
+  | { type: 'link'; url: string; target?: '_blank' | '_self' }; // 外链
+
+export interface AppendContainerProps { openPanel: (action: PanelAction) => void }
+export interface PageProps { close: () => void }
+```
+
+```tsx
+function ReportPage({ close }: PageProps) {
+  return (
+    <div style={{ padding: 16 }}>
+      报告内容……
+      <button onClick={close}>返回</button>
+    </div>
+  );
+}
+
+function MyHomeBlock({ openPanel }: AppendContainerProps) {
+  return (
+    <>
+      <button onClick={() => openPanel({ type: "page", component: ReportPage, title: "全景报告" })}>
+        整屏容器
+      </button>
+      <button onClick={() => openPanel({ type: "link", url: "https://example.com" })}>
+        新窗口外链
+      </button>
+    </>
+  );
+}
+
+mount("#app", { sdk, slots: { AppendContainer: MyHomeBlock } });
+```
+
+要开「第 3 条记录」这类带参数的页面，直接给**元素**，SDK 用 `cloneElement` 补上 `close`：
+
+```tsx
+// 元素形态下 close 声明为可选，才能写 <DetailPage id={3} />（运行时 SDK 必然注入）
+function DetailPage({ id, close }: { id: number; close?: () => void }) {
+  return <button onClick={close}>详情 #{id} 返回</button>;
+}
+
+openPanel({ type: "page", component: <DetailPage id={3} />, title: "详情 #3" });
+```
+
+给组件类型（`component: DetailPage`）时 `close` 是必填 prop，同样由 SDK 注入。
+
+连定制区都不想写？首屏「快速入口」吃同一个 `action`，纯配置即可接入（`title` 缺省用 `label`）：
+
+```tsx
+mount("#app", {
+  sdk,
+  quickLinks: [
+    { label: "全景报告", action: { type: "page", component: ReportPage } },
+    { label: "帮助文档", action: { type: "link", url: "https://example.com/help" } },
+  ],
+});
+```
+
+点击优先级：`onClick > action > prompt`。
+
+整屏容器行为：
+
+| 项 | 表现 |
+| --- | --- |
+| 呈现 | 替换「内容区 + 输入区」，Header 保留（小窗仍可拖拽）；`link` 走 `window.open`，不占状态 |
+| 标题栏 | 返回箭头 + `title`（可选）；`Esc` 等价返回 |
+| 窗口几何 | 保持打开前窗态，小窗不自动升大窗；内容在容器内滚动（业务页不写滚动容器） |
+| 关闭 | 返回 / `close()` / `Esc`；关闭聊天面板时一并清掉 |
+| 栈 | 单层不叠栈，容器内部导航由业务组件自己管 |
+
+注意：浮层组件渲染在 SDK 自己的 `createRoot` 树内，拿不到宿主的 React Context / Router。组件引用直接给，不需要注册表——类型即校验。
+
 ### 8.4 事件钩子（EventHooks）
 
 通过 `hooks` 监听组件生命周期与交互事件：
@@ -1347,6 +1509,7 @@ export type MessagePart =
       html?: string;
     }
   | { type: "error"; content: string }
+  | { type: "attachment"; attachment: ChatAttachment } // 用户消息携带的附件 chip
   | {
       type: "interrupt";
       interrupt: InterruptEvent;
@@ -1362,6 +1525,7 @@ export type MessagePart =
 | `tool_call`   | `toolName`, `toolCallId`, `args`                                          | 工具调用，`args` 为 JSON 字符串 |
 | `tool_result` | `toolName`, `toolCallId`, `content`, `artifacts?`, `renderMode?`, `html?` | 工具返回结果                    |
 | `error`       | `content`                                                                 | 错误信息                        |
+| `attachment`  | `attachment`                                                              | 用户消息附件 chip（发送时本地构造 / 历史加载由后端映射，有 `url` 时可下载） |
 | `interrupt`   | `interrupt`, `resolved?`, `response?`                                     | 中断交互卡片（HITL）            |
 
 ### 11.3 ChatEvent（流式事件）

package/dist/index.cjs

@@ -1,5 +1,5 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function u(r){if(Array.isArray(r))return r.map(e=>u(e));if(r&&typeof r=="object"&&r.constructor===Object){const e={};for(const[t,s]of Object.entries(r)){const o=t.replace(/_([a-z])/g,(a,n)=>n.toUpperCase());e[o]=u(s)}return e}return r}const I="/api/agent/runtime/v1";class w{constructor(e){this.refreshing=null;const t=e.baseUrl??I;this.baseUrl=t.replace(/\/$/,""),this.tokenGateway=e.tokenGateway.replace(/\/$/,""),this.appId=e.appId??"",this.token=e.token??"",this.botId=e.botId,this.isAbsoluteUrl=/^https?:\/\//.test(this.baseUrl),this.isAbsoluteGateway=/^https?:\/\//.test(this.tokenGateway)}getBotId(){return this.botId}getAppKey(){return this.appId}setToken(e){this.token=e}getOrigin(){return typeof window<"u"?window.location.origin:""}async fetchToken(){const t=`${this.isAbsoluteGateway?this.tokenGateway:`${this.getOrigin()}${this.tokenGateway}`}/v1/token`,s=await fetch(t,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({botId:this.botId})});if(!s.ok)throw new Error(`HTTP ${s.status}: ${s.statusText}`);const o=await s.json();if(o.code!=="200")throw new Error(o.message||`API error: ${o.code}`);const a=u(o.data);return this.token=a.token,a.appId&&!this.appId&&(this.appId=a.appId),a.token}headers(e){return{"Content-Type":"application/json","X-App-Id":this.appId,"X-Token":this.token,...e}}async handleTokenRefresh(){if(this.refreshing)return await this.refreshing,!0;try{return this.refreshing=(async()=>{await this.fetchToken()})(),await this.refreshing,!0}catch{return!1}finally{this.refreshing=null}}async request(e,t,s){if(!this.token&&!await this.handleTokenRefresh())throw new Error("SDK token not available: POST /token failed");let o=this.isAbsoluteUrl?`${this.baseUrl}${t}`:`${this.getOrigin()}${this.baseUrl}${t}`;if(s!=null&&s.params){const i=new URLSearchParams;for(const[d,l]of Object.entries(s.params))l!=null&&i.set(d,String(l));const c=i.toString();c&&(o+=`?${c}`)}const a=await fetch(o,{method:e,headers:this.headers(),body:s!=null&&s.body?JSON.stringify(s.body):void 0});if(a.status===401&&!(s!=null&&s.retry)&&await this.handleTokenRefresh())return this.request(e,t,{...s,retry:!0});if(!a.ok)throw new Error(`HTTP ${a.status}: ${a.statusText}`);const n=await a.json();if(n.code!=="200")throw new Error(n.message||`API error: ${n.code}`);return u(n.data)}get(e,t){return this.request("GET",e,{params:t})}post(e,t){return this.request("POST",e,{body:t})}patch(e,t){return this.request("PATCH",e,{body:t})}del(e){return this.request("DELETE",e)}async streamPost(e,t,s){if(!this.token&&!await this.handleTokenRefresh())throw new Error("SDK token not available: POST /token failed");const o=this.isAbsoluteUrl?`${this.baseUrl}${e}`:`${this.getOrigin()}${this.baseUrl}${e}`,a=await fetch(o,{method:"POST",headers:this.headers(),body:JSON.stringify(t),signal:s});return a.status===401&&await this.handleTokenRefresh()?fetch(o,{method:"POST",headers:this.headers(),body:JSON.stringify(t),signal:s}):a}}function y(r){const e=r.split(`
-`).map(s=>s.trim()).filter(s=>s.startsWith("data:")).map(s=>s.slice(5).trim());if(!e.length)return null;let t;try{t=JSON.parse(e.join(`
-`))}catch{return null}switch(t.type){case"user":return{type:"user",content:t.content??""};case"thinking":return{type:"thinking",content:t.content??""};case"ai":return{type:"ai",content:t.content??""};case"tool_call":return{type:"tool_call",content:t.name??"",toolName:t.name,toolCallId:t.id,args:typeof t.args=="string"?t.args:JSON.stringify(t.args??{})};case"tool_result":return{type:"tool_result",content:t.output??"",toolName:t.name,toolCallId:t.id,artifacts:Array.isArray(t.artifacts)?t.artifacts:void 0,renderMode:t.render_mode??t.renderMode,html:t.html};case"done":return{type:"done",content:t.content??"",sessionId:t.sessionId??t.session_id??"",messageId:t.messageId??t.message_id};case"stop":return{type:"stop",content:t.content??"",sessionId:t.sessionId??t.session_id??"",messageId:t.messageId??t.message_id};case"error":return{type:"error",content:t.message??"Unknown error"};case"interrupt":return{type:"interrupt",content:t.content??"",interrupt:{interruptId:t.interruptId??t.interrupt_id??"",interruptType:t.interruptType??t.interrupt_type??"confirm",content:t.content??"",options:t.options,placeholder:t.placeholder,inputType:t.inputType??t.input_type,maxLength:t.maxLength??t.max_length,required:t.required,fields:t.fields,metadata:t.metadata}};default:return null}}async function m(r,e,t){if(!r.body){t(new Error("Response body is null"));return}const s=r.body.getReader(),o=new TextDecoder;let a="";try{for(;;){const{value:n,done:i}=await s.read();if(i)break;a+=o.decode(n,{stream:!0});let c;for(;(c=a.indexOf(`
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const w=require("./nosUploader-KkzFK5EW.cjs");function h(r){if(Array.isArray(r))return r.map(e=>h(e));if(r&&typeof r=="object"&&r.constructor===Object){const e={};for(const[t,n]of Object.entries(r)){const i=t.replace(/_([a-z])/g,(a,s)=>s.toUpperCase());e[i]=h(n)}return e}return r}const T="/api/agent/runtime/v1";class k{constructor(e){this.refreshing=null;const t=e.baseUrl??T;this.baseUrl=t.replace(/\/$/,""),this.tokenGateway=e.tokenGateway.replace(/\/$/,""),this.appId=e.appId??"",this.token=e.token??"",this.botId=e.botId,this.isAbsoluteUrl=/^https?:\/\//.test(this.baseUrl),this.isAbsoluteGateway=/^https?:\/\//.test(this.tokenGateway)}getBotId(){return this.botId}getAppKey(){return this.appId}setToken(e){this.token=e}getOrigin(){return typeof window<"u"?window.location.origin:""}async fetchToken(){const t=`${this.isAbsoluteGateway?this.tokenGateway:`${this.getOrigin()}${this.tokenGateway}`}/v1/token`,n=await fetch(t,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({botId:this.botId})});if(!n.ok)throw new Error(`HTTP ${n.status}: ${n.statusText}`);const i=await n.json();if(i.code!=="200")throw new Error(i.message||`API error: ${i.code}`);const a=h(i.data);return this.token=a.token,a.appId&&!this.appId&&(this.appId=a.appId),a.token}headers(e){return{"Content-Type":"application/json","X-App-Id":this.appId,"X-Token":this.token,...e}}async handleTokenRefresh(){if(this.refreshing)return await this.refreshing,!0;try{return this.refreshing=(async()=>{await this.fetchToken()})(),await this.refreshing,!0}catch{return!1}finally{this.refreshing=null}}async request(e,t,n){if(!this.token&&!await this.handleTokenRefresh())throw new Error("SDK token not available: POST /token failed");let i=this.isAbsoluteUrl?`${this.baseUrl}${t}`:`${this.getOrigin()}${this.baseUrl}${t}`;if(n!=null&&n.params){const o=new URLSearchParams;for(const[d,l]of Object.entries(n.params))l!=null&&o.set(d,String(l));const c=o.toString();c&&(i+=`?${c}`)}const a=await fetch(i,{method:e,headers:this.headers(),body:n!=null&&n.body?JSON.stringify(n.body):void 0});if(a.status===401&&!(n!=null&&n.retry)&&await this.handleTokenRefresh())return this.request(e,t,{...n,retry:!0});if(!a.ok)throw new Error(`HTTP ${a.status}: ${a.statusText}`);const s=await a.json();if(s.code!=="200")throw new Error(s.message||`API error: ${s.code}`);return h(s.data)}get(e,t){return this.request("GET",e,{params:t})}post(e,t){return this.request("POST",e,{body:t})}patch(e,t){return this.request("PATCH",e,{body:t})}del(e){return this.request("DELETE",e)}async streamPost(e,t,n){if(!this.token&&!await this.handleTokenRefresh())throw new Error("SDK token not available: POST /token failed");const i=this.isAbsoluteUrl?`${this.baseUrl}${e}`:`${this.getOrigin()}${this.baseUrl}${e}`,a=await fetch(i,{method:"POST",headers:this.headers(),body:JSON.stringify(t),signal:n});return a.status===401&&await this.handleTokenRefresh()?fetch(i,{method:"POST",headers:this.headers(),body:JSON.stringify(t),signal:n}):a}}function u(r){return typeof r=="string"?r:Array.isArray(r)?r.map(e=>{if(typeof e=="string")return e;if(e&&typeof e=="object"){if(typeof e.text=="string")return e.text;if(e.type)return`[${e.type}${e.mime_type?": "+e.mime_type:""}]`}return""}).join(""):r==null?"":String(r)}function I(r){const e=r.split(`
+`).map(n=>n.trim()).filter(n=>n.startsWith("data:")).map(n=>n.slice(5).trim());if(!e.length)return null;let t;try{t=JSON.parse(e.join(`
+`))}catch{return null}switch(t.type){case"user":return{type:"user",content:u(t.content)};case"thinking":return{type:"thinking",content:u(t.content)};case"ai":return{type:"ai",content:u(t.content)};case"tool_call":return{type:"tool_call",content:t.name??"",toolName:t.name,toolCallId:t.id,args:typeof t.args=="string"?t.args:JSON.stringify(t.args??{})};case"tool_result":return{type:"tool_result",content:u(t.output),toolName:t.name,toolCallId:t.id,artifacts:Array.isArray(t.artifacts)?t.artifacts:void 0,renderMode:t.render_mode??t.renderMode,html:t.html};case"done":return{type:"done",content:u(t.content),sessionId:t.sessionId??t.session_id??"",messageId:t.messageId??t.message_id};case"stop":return{type:"stop",content:u(t.content),sessionId:t.sessionId??t.session_id??"",messageId:t.messageId??t.message_id};case"error":return{type:"error",content:t.message??"Unknown error"};case"interrupt":return{type:"interrupt",content:t.content??"",interrupt:{interruptId:t.interruptId??t.interrupt_id??"",interruptType:t.interruptType??t.interrupt_type??"confirm",content:t.content??"",options:t.options,placeholder:t.placeholder,inputType:t.inputType??t.input_type,maxLength:t.maxLength??t.max_length,required:t.required,fields:t.fields,metadata:t.metadata}};default:return null}}async function p(r,e,t){if(!r.body){t(new Error("Response body is null"));return}const n=r.body.getReader(),i=new TextDecoder;let a="";try{for(;;){const{value:s,done:o}=await n.read();if(o)break;a+=i.decode(s,{stream:!0});let c;for(;(c=a.indexOf(`
 
-`))!==-1;){const d=a.slice(0,c);a=a.slice(c+2);const l=y(d);l&&e(l)}}if(a.trim()){const n=y(a);n&&e(n)}}catch(n){(n==null?void 0:n.name)!=="AbortError"&&t(n instanceof Error?n:new Error(String(n)))}finally{try{s.releaseLock()}catch{}}}function b(r,e){const t=new AbortController,s=e.signal?p(e.signal,t.signal):t.signal,o={botId:r.getBotId(),message:e.message,sessionId:e.sessionId,stream:e.stream!==!1};return o.stream?r.streamPost("/chat",o,s).then(a=>{var n;if(!a.ok){(n=e.onError)==null||n.call(e,new Error(`HTTP ${a.status}`));return}return m(a,i=>{var c,d,l,h,f,g;i.type==="done"&&i.sessionId?(c=e.onDone)==null||c.call(e,{sessionId:i.sessionId,content:i.content,messageId:i.messageId}):i.type==="done"?(d=e.onDone)==null||d.call(e,{sessionId:"",content:i.content,messageId:i.messageId}):i.type==="stop"?((l=e.onMessage)==null||l.call(e,i),(h=e.onDone)==null||h.call(e,{sessionId:i.sessionId??"",content:i.content,messageId:i.messageId})):i.type==="error"?(f=e.onError)==null||f.call(e,new Error(i.content)):(g=e.onMessage)==null||g.call(e,i)},i=>{var c;return(c=e.onError)==null?void 0:c.call(e,i)})}).catch(a=>{var n;(a==null?void 0:a.name)!=="AbortError"&&((n=e.onError)==null||n.call(e,a instanceof Error?a:new Error(String(a))))}):r.post("/chat",o).then(a=>{var n;(n=e.onDone)==null||n.call(e,{sessionId:a.sessionId,content:a.content??"",messageId:a.messageId})}).catch(a=>{var n;(n=e.onError)==null||n.call(e,a instanceof Error?a:new Error(String(a)))}),t}function p(r,e){const t=new AbortController,s=()=>t.abort();return r.addEventListener("abort",s,{once:!0}),e.addEventListener("abort",s,{once:!0}),(r.aborted||e.aborted)&&t.abort(),t.signal}async function T(r){return(await r.post("/chat/sessions",{botId:r.getBotId()})).sessionId}function k(r){return{sessionId:r.threadId??r.sessionId,botId:r.botId,title:r.title,createTime:r.createTime,updateTime:r.updateTime}}async function S(r,e){const t=await r.get("/chat/conversations",{botId:r.getBotId(),page:(e==null?void 0:e.page)??1,size:(e==null?void 0:e.size)??20});return{...t,items:t.items.map(k)}}async function $(r,e,t){await r.patch(`/chat/conversations/${e}`,{title:t})}async function A(r,e){await r.del(`/chat/conversations/${e}`)}async function C(r,e){const t=await r.get(`/chat/conversations/${e}/messages`);return O(t)}function O(r){const e=[...r].sort((n,i)=>{const c=new Date(n.createTime??0).getTime()||0,d=new Date(i.createTime??0).getTime()||0;return c!==d?c-d:(n.seq??0)-(i.seq??0)}),t=new Map;for(const n of e)n.role==="tool"&&n.toolCallId&&t.set(n.toolCallId,n.content||"");const s=new Set,o=[],a=(n,i,c)=>{const d=o[o.length-1];(d==null?void 0:d.role)==="assistant"?(d.parts.push(...n),d.id=i):o.push({id:i,role:"assistant",parts:[...n],timestamp:c})};for(const n of e){if(n.role==="system")continue;const i=String(n.id??n.messageId??`msg_${Date.now()}`),c=new Date(n.createTime??"").getTime()||Date.now();if(n.role==="human"){o.push({id:i,role:"user",parts:[{type:"text",content:n.content??""}],timestamp:c});continue}if(n.role==="ai"){const d=P(n,t,s);d.length>0&&a(d,i,c);continue}if(n.role==="tool"){if(n.toolCallId&&s.has(n.toolCallId))continue;a([v(n)],i,c)}}return o}function P(r,e,t){const s=[];r.reasoning&&s.push({type:"thinking",content:r.reasoning}),r.content&&s.push({type:"text",content:r.content});for(const o of r.toolCalls??[])o.is_interrupt?(t.add(o.id),s.push(_(o,e))):s.push(E(o));return s}function _(r,e){const t=e.has(r.id),s=typeof r.args=="object"?r.args:{};return{type:"interrupt",interrupt:{interruptId:r.id??"",interruptType:s.interruptType??"input",content:s.content??"",options:s.options,placeholder:s.placeholder,inputType:s.inputType,maxLength:s.maxLength,required:s.required,fields:s.fields,metadata:s.metadata},resolved:t,response:t?{action:"submit",value:U(e.get(r.id))}:void 0}}function E(r){let e;try{e=typeof r.args=="string"?r.args:JSON.stringify(r.args??{})}catch{e=String(r.args??"{}")}return{type:"tool_call",toolName:r.name??"",toolCallId:r.id??"",args:e}}function v(r){var t,s,o;const e=Array.isArray(r.artifacts)?r.artifacts:void 0;return{type:"tool_result",toolName:r.toolName??"",toolCallId:r.toolCallId??"",content:r.content??"",artifacts:e,renderMode:((t=r.metadata)==null?void 0:t.renderMode)??((s=r.metadata)==null?void 0:s.render_mode),html:(o=r.metadata)==null?void 0:o.html}}function U(r){if(r!=null)try{return JSON.parse(r)}catch{return r}}async function x(r,e,t,s,o,a){const n=await r.streamPost(`/chat/interrupt/${e}/respond`,{sessionId:t,action:s.action,value:s.value});if(!n.ok){const i=new Error(`HTTP ${n.status}`);throw a==null||a(i),i}o&&await m(n,i=>{i.type==="error"?a==null||a(new Error(i.content)):o(i)},i=>a==null?void 0:a(i))}async function D(r){return r.get(`/chat/bots/${r.getBotId()}/skills`)}async function q(r,e){await r.post("/chat/stop",{sessionId:e})}function N(r){const e=new w(r);return{botId:e.getBotId(),getToken:()=>e.fetchToken(),createSession:()=>T(e),chat:s=>b(e,s),listConversations:s=>S(e,s),renameConversation:(s,o)=>$(e,s,o),deleteConversation:s=>A(e,s),getMessages:s=>C(e,s),respondInterrupt:(s,o,a,n,i)=>x(e,s,o,a,n,i),setToken:s=>e.setToken(s),feedback:async(s,o,a)=>{const n={type:o};o==="dislike"&&((a==null?void 0:a.reason)!=null&&(n.reason=a.reason),a!=null&&a.remark&&(n.remark=a.remark)),await e.post(`/chat/messages/${s}/feedback`,n)},cancelFeedback:async s=>{await e.del(`/chat/messages/${s}/feedback`)},listSkills:()=>D(e),stopGeneration:s=>q(e,s)}}exports.createSuperAgent=N;
+`))!==-1;){const d=a.slice(0,c);a=a.slice(c+2);const l=I(d);l&&e(l)}}if(a.trim()){const s=I(a);s&&e(s)}}catch(s){(s==null?void 0:s.name)!=="AbortError"&&t(s instanceof Error?s:new Error(String(s)))}finally{try{n.releaseLock()}catch{}}}function b(r,e){var a;const t=new AbortController,n=e.signal?S(e.signal,t.signal):t.signal,i={botId:r.getBotId(),message:e.message,sessionId:e.sessionId,stream:e.stream!==!1,...(a=e.attachments)!=null&&a.length?{attachments:e.attachments.map(({url:s,...o})=>o)}:{}};return i.stream?r.streamPost("/chat",i,n).then(s=>{var o;if(!s.ok){(o=e.onError)==null||o.call(e,new Error(`HTTP ${s.status}`));return}return p(s,c=>{var d,l,f,g,y,m;c.type==="done"&&c.sessionId?(d=e.onDone)==null||d.call(e,{sessionId:c.sessionId,content:c.content,messageId:c.messageId}):c.type==="done"?(l=e.onDone)==null||l.call(e,{sessionId:"",content:c.content,messageId:c.messageId}):c.type==="stop"?((f=e.onMessage)==null||f.call(e,c),(g=e.onDone)==null||g.call(e,{sessionId:c.sessionId??"",content:c.content,messageId:c.messageId})):c.type==="error"?(y=e.onError)==null||y.call(e,new Error(c.content)):(m=e.onMessage)==null||m.call(e,c)},c=>{var d;return(d=e.onError)==null?void 0:d.call(e,c)})}).catch(s=>{var o;(s==null?void 0:s.name)!=="AbortError"&&((o=e.onError)==null||o.call(e,s instanceof Error?s:new Error(String(s))))}):r.post("/chat",i).then(s=>{var o;(o=e.onDone)==null||o.call(e,{sessionId:s.sessionId,content:s.content??"",messageId:s.messageId})}).catch(s=>{var o;(o=e.onError)==null||o.call(e,s instanceof Error?s:new Error(String(s)))}),t}function S(r,e){const t=new AbortController,n=()=>t.abort();return r.addEventListener("abort",n,{once:!0}),e.addEventListener("abort",n,{once:!0}),(r.aborted||e.aborted)&&t.abort(),t.signal}async function $(r){return(await r.post("/chat/sessions",{botId:r.getBotId()})).sessionId}function A(r){return{sessionId:r.threadId??r.sessionId,botId:r.botId,title:r.title,createTime:r.createTime,updateTime:r.updateTime}}async function C(r,e){const t=await r.get("/chat/conversations",{botId:r.getBotId(),page:(e==null?void 0:e.page)??1,size:(e==null?void 0:e.size)??20});return{...t,items:t.items.map(A)}}async function _(r,e,t){await r.patch(`/chat/conversations/${e}`,{title:t})}async function O(r,e){await r.del(`/chat/conversations/${e}`)}async function P(r,e){const t=await r.get(`/chat/conversations/${e}/messages`);return E(t)}function E(r){const e=[...r].sort((s,o)=>{const c=new Date(s.createTime??0).getTime()||0,d=new Date(o.createTime??0).getTime()||0;return c!==d?c-d:(s.seq??0)-(o.seq??0)}),t=new Map;for(const s of e)s.role==="tool"&&s.toolCallId&&t.set(s.toolCallId,s.content||"");const n=new Set,i=[],a=(s,o,c)=>{const d=i[i.length-1];(d==null?void 0:d.role)==="assistant"?(d.parts.push(...s),d.id=o):i.push({id:o,role:"assistant",parts:[...s],timestamp:c})};for(const s of e){if(s.role==="system")continue;const o=String(s.id??s.messageId??`msg_${Date.now()}`),c=new Date(s.createTime??"").getTime()||Date.now();if(s.role==="human"){const d=(s.attachments??[]).map(l=>({type:"attachment",attachment:{nosKey:l.nosKey??l.attachmentId??"",filename:l.filename??"file",size:l.size??void 0,mime:l.mime??void 0,url:l.url??void 0}}));i.push({id:o,role:"user",parts:[...d,{type:"text",content:u(s.content)}],timestamp:c});continue}if(s.role==="ai"){const d=U(s,t,n);d.length>0&&a(d,o,c);continue}if(s.role==="tool"){if(s.toolCallId&&n.has(s.toolCallId))continue;a([N(s)],o,c)}}return i}function U(r,e,t){const n=[];r.reasoning&&n.push({type:"thinking",content:r.reasoning}),r.content&&n.push({type:"text",content:u(r.content)});for(const i of r.toolCalls??[])i.is_interrupt?(t.add(i.id),n.push(x(i,e))):n.push(v(i));return n}function x(r,e){const t=e.has(r.id),n=typeof r.args=="object"?r.args:{};return{type:"interrupt",interrupt:{interruptId:r.id??"",interruptType:n.interruptType??"input",content:n.content??"",options:n.options,placeholder:n.placeholder,inputType:n.inputType,maxLength:n.maxLength,required:n.required,fields:n.fields,metadata:n.metadata},resolved:t,response:t?{action:"submit",value:q(e.get(r.id))}:void 0}}function v(r){let e;try{e=typeof r.args=="string"?r.args:JSON.stringify(r.args??{})}catch{e=String(r.args??"{}")}return{type:"tool_call",toolName:r.name??"",toolCallId:r.id??"",args:e}}function N(r){var t,n,i;const e=Array.isArray(r.artifacts)?r.artifacts:void 0;return{type:"tool_result",toolName:r.toolName??"",toolCallId:r.toolCallId??"",content:u(r.content),artifacts:e,renderMode:((t=r.metadata)==null?void 0:t.renderMode)??((n=r.metadata)==null?void 0:n.render_mode),html:(i=r.metadata)==null?void 0:i.html}}function q(r){if(r!=null)try{return JSON.parse(r)}catch{return r}}async function D(r,e,t,n,i,a){const s=await r.streamPost(`/chat/interrupt/${e}/respond`,{sessionId:t,action:n.action,value:n.value});if(!s.ok){const o=new Error(`HTTP ${s.status}`);throw a==null||a(o),o}i&&await p(s,o=>{o.type==="error"?a==null||a(new Error(o.content)):i(o)},o=>a==null?void 0:a(o))}async function L(r){return r.get(`/chat/bots/${r.getBotId()}/skills`)}async function G(r,e){await r.post("/chat/stop",{sessionId:e})}function M(r){const e=new k(r);return{botId:e.getBotId(),getToken:()=>e.fetchToken(),createSession:()=>$(e),chat:n=>b(e,n),listConversations:n=>C(e,n),renameConversation:(n,i)=>_(e,n,i),deleteConversation:n=>O(e,n),getMessages:n=>P(e,n),respondInterrupt:(n,i,a,s,o)=>D(e,n,i,a,s,o),setToken:n=>e.setToken(n),feedback:async(n,i,a)=>{const s={type:i};i==="dislike"&&((a==null?void 0:a.reason)!=null&&(s.reason=a.reason),a!=null&&a.remark&&(s.remark=a.remark)),await e.post(`/chat/messages/${n}/feedback`,s)},cancelFeedback:async n=>{await e.del(`/chat/messages/${n}/feedback`)},listSkills:()=>L(e),stopGeneration:n=>G(e,n)}}exports.createNosUploader=w.createNosUploader;exports.createSuperAgent=M;

package/dist/index.d.ts

@@ -14,6 +14,15 @@ export declare interface ArtifactFile {
     summary?: string;
 }
 
+/** 附件描述：前端直传 NOS（如 @netease-ehr/ui Upload 的 nosUpload onSuccess 结果）提取。 */
+export declare interface ChatAttachment {
+    nosKey: string;
+    filename: string;
+    size?: number;
+    mime?: string;
+    url?: string;
+}
+
 export declare interface ChatEvent {
     type: "user" | "thinking" | "ai" | "tool_call" | "tool_result" | "done" | "stop" | "error" | "interrupt";
     content: string;
@@ -31,6 +40,8 @@ export declare interface ChatEvent {
 export declare interface ChatOptions {
     sessionId: string;
     message: string;
+    /** 附件（仅沙箱模式 Agent 支持，其他模式后端返回 400）。需先经直传组件传到 NOS 拿到 nosKey。 */
+    attachments?: ChatAttachment[];
     stream?: boolean;
     onMessage?: (event: ChatEvent) => void;
     onError?: (error: Error) => void;
@@ -50,6 +61,15 @@ export declare interface Conversation {
     updateTime: string;
 }
 
+/**
+ * 创建 NOS 直传上传器（attachmentUploader 形态：File → Promise<ChatAttachment>）。
+ *
+ * 与 @netease-ehr/ui Upload nosUpload 的行为对齐：
+ * - nosKey 生成算法一致（MD5(name:size:timestamp)）—— 与原组件共存在同一桶内无冲突
+ * - 断点续传：nos-js-sdk 经 localStorage 记录 progress/context，同文件重传自动续传
+ */
+export declare function createNosUploader(config: NosUploaderConfig): (file: File) => Promise<ChatAttachment>;
+
 export declare function createSuperAgent(config: SDKConfig): SuperAgentSDK;
 
 export declare interface FormField {
@@ -125,6 +145,9 @@ export declare type MessagePart = {
 } | {
     type: "error";
     content: string;
+} | {
+    type: "attachment";
+    attachment: ChatAttachment;
 } | {
     type: "interrupt";
     interrupt: InterruptEvent;
@@ -132,6 +155,23 @@ export declare type MessagePart = {
     response?: InterruptResponse;
 };
 
+export declare interface NosUploaderConfig {
+    /** 业务网关（通常与业务系统接口网关保持一致，如 "/api/e5s"） */
+    baseURL: string;
+    /** 网关自定义请求头（鉴权等，token/url GET 携带） */
+    headers?: Record<string, string>;
+    /** 分片大小（默认 4MB，合法值 (0, 4MB]） */
+    trunkSize?: number;
+    /** 上传进度回调（0-100） */
+    onProgress?: (percent: number) => void;
+    /** 单分片 XHR 超时（默认 120s；nos-js-sdk 默认 50s，慢环境 commit 易超时静默死亡） */
+    chunkTimeoutMs?: number;
+    /** 无进度看门狗（默认 130s：超过此时长无任何进度事件且未完成 → 显式报错） */
+    stallTimeoutMs?: number;
+    /** 上传完成后调 /nos/url 取下载地址（默认 true，对齐原组件；失败降级不影响上传结果） */
+    fetchNosUrl?: boolean;
+}
+
 export declare interface SDKConfig {
     botId: number;
     tokenGateway: string;