super-agent-sdk 1.0.9 → 1.0.10

package/README.md

@@ -430,7 +430,8 @@ export interface QuickLinkItem {
   icon?: string; // 图标 URL
   label: string; // 入口名称
   prompt?: string; // 点击后发送的消息
-  onClick?: () => void; // 自定义点击行为（优先于 prompt）
+  action?: PanelAction; // 点击行为：整屏容器 / 外链（优先于 prompt）
+  onClick?: () => void; // 自定义点击行为（优先于 action / prompt）
 }
 
 export interface WidgetInstance {
@@ -513,10 +514,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 +611,8 @@ export interface Slots {
   ErrorPart?: ComponentType<ErrorPartProps>;
   InterruptCard?: ComponentType<InterruptCardProps>;
   WelcomeScreen?: ComponentType<WelcomeScreenProps>;
+  /** 首屏底部业务定制容器 */
+  AppendContainer?: ComponentType<AppendContainerProps>;
 }
 ```
 
@@ -627,6 +630,7 @@ export interface Slots {
 | `ToolResultPart` | `ToolResultPartProps` | 工具返回卡片（pre 滚动 + 复制；`renderMode==="html"` 时 DOMPurify 清洗后直接渲染，最高 60vh 滚动） |
 | `ErrorPart`      | `ErrorPartProps`      | 错误提示块                                                                                         |
 | `WelcomeScreen`  | `WelcomeScreenProps`  | 空会话欢迎页                                                                                       |
+| `AppendContainer`| `AppendContainerProps`| 首屏底部业务定制区，`openPanel(action)` 开整屏容器或外链（见下）                                   |
 
 #### Trigger
 
@@ -965,6 +969,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` 监听组件生命周期与交互事件：