@ibiz-template-plugin/ai-chat 0.0.113 → 0.0.115

package/dist/types/components/chat-container/chat-container.d.ts

@@ -1,6 +1,6 @@
 import { Component, JSX } from 'preact';
 import { Namespace } from '../../utils';
-import { AiChatController, AiTopicController } from '../../controller';
+import { AiActionPanelController, AiChatController, AiTopicController } from '../../controller';
 import { IAutoClose, IChatToolbarItem, IChatContainerOptions } from '../../interface';
 
 export interface ChatContainerProps {
@@ -101,6 +101,13 @@ export interface ChatContainerProps {
      * 是否加载中
      */
     isLoading: boolean;
+    /**
+     * 操作区面板控制器
+     *
+     * @type {AiActionPanelController}
+     * @memberof ChatContainerProps
+     */
+    actionPanel?: AiActionPanelController;
 }
 /**
  * 容器状态
@@ -152,6 +159,13 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
      * 已绑定事件监听的聊天控制器实例（用于切换 aiChat 时重绑）
      */
     private listenedAIChat?;
+    /**
+     * @description 拖拽实例
+     * @private
+     * @type {(Interactable | undefined)}
+     * @memberof ChatContainer
+     */
+    private interactable;
     /**
      * 消息完成事件回调
      */
@@ -162,6 +176,38 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
     private onMinimizeChangeHandler;
     listener(): void;
     componentDidUpdate(): void;
+    /**
+     *
+     * 同步操作区面板状态（visible 边沿触发窗口宽度增减与位置适配，展开收起动画由 CSS 过渡完成）
+     *
+     * @memberof ChatContainer
+     */
+    syncPanelState(): void;
+    /**
+     * 打开操作区面板：窗口增宽面板占用（面板 + 分隔条），右边界不够时压缩面板宽度，仍不够则窗口左移补足
+     *
+     * @param {AiActionPanelController} panel
+     * @memberof ChatContainer
+     */
+    handlePanelOpen(panel: AiActionPanelController): void;
+    /**
+     * 关闭操作区面板：窗口宽度回落面板占用（面板 + 分隔条），并回退打开时的窗口左移量
+     *
+     * @memberof ChatContainer
+     */
+    handlePanelClose(): void;
+    /**
+     * 恢复面板打开期间为适配右边界所做的窗口左移量
+     */
+    restorePanelShift(): void;
+    /**
+     * 面板打开后适配屏幕右边界（全屏时窗口铺满屏幕无需适配）
+     * - 先压缩面板宽度（窗口总宽同步回落），仍溢出则窗口左移补足
+     *
+     * @param {AiActionPanelController} panel
+     * @memberof ChatContainer
+     */
+    fitPanelToViewport(panel: AiActionPanelController): void;
     ns: Namespace;
     containerRef: import('preact').RefObject<HTMLDivElement>;
     dragHandle: import('preact').RefObject<HTMLDivElement>;
@@ -176,16 +222,16 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
      */
     data: {
         side: {
+            x: number;
             y: number;
-            height: number;
             width: number;
-            x: number;
+            height: number;
         };
         window: {
+            x: number;
             y: number;
             width: number;
             height: number;
-            x: number;
         };
         minWidth: number;
         minHeight: number;
@@ -224,6 +270,18 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
      * 输入区高度拖动时其父容器高度(px)
      */
     inputDragContainerHeight: number;
+    /**
+     * 操作区面板上一帧显示状态（用于 componentDidUpdate 边沿检测）
+     */
+    private panelVisiblePrev;
+    /**
+     * 操作区面板打开导致的窗口左移量(px)，关闭面板时恢复（不持久化）
+     */
+    private panelShiftPx;
+    /**
+     * 操作区面板宽度拖动起始值(px)
+     */
+    private panelDragStartWidth;
     /**
      * 容器上下文
      *
@@ -249,6 +307,7 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
     };
     /**
      * 计算靠边模式样式
+     * - 贴右模式下面板打开时窗口整体左移，保证右边缘不超出屏幕
      *
      * @param {('left' | 'right')} side
      * @memberof ChatContainer
@@ -393,6 +452,24 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
      * 提交拖动边框后的输入区高度（持久化到状态与本地缓存）
      */
     commitInputHeight: () => void;
+    /**
+     * 操作区面板宽度拖动开始
+     */
+    handlePanelResizeStart: () => void;
+    /**
+     * 操作区面板宽度拖动中
+     * - 向左拖：主内容区变窄、面板变宽；向右拖反之
+     */
+    handlePanelResizeMove: (delta: number) => void;
+    /**
+     * 操作区面板宽度拖动结束（持久化）
+     */
+    handlePanelResizeEnd: () => void;
+    /**
+     * 绘制右侧操作区（含分隔条）
+     * - DOM 常驻，宽度随 visible 切换由 CSS 过渡展开/收起
+     */
+    renderActionRegion(): JSX.Element | null;
     render(): JSX.Element;
 }
 export {};

package/dist/types/components/chat-editor/node/mention-node.d.ts

@@ -0,0 +1,3 @@
+import { Node } from '@tiptap/core';
+
+export declare const MentionNode: Node<any, any>;

package/dist/types/components/chat-messages/chat-messages.d.ts

@@ -31,7 +31,8 @@ export interface ChatMessageProps {
  * 消息数量 / 内容会随时变化，滚动位置由下面的「锚定策略」维护。
  *
  * ## 锚定策略（useLayoutEffect 内）
- * 1. 末尾追加（发消息 / AI 回复）→ 强制贴底，跟随新消息；
+ * 1. 末尾追加：用户自己发送的消息 → 强制贴底，跟随新消息；AI 回复 → 遵循当前贴底状态
+ *    （用户上翻阅读历史时不被打断，落入下方分支 2/3 处理）；
  * 2. 贴底模式（isAutoScroll）下任何变化（流式增长、测量回填）→ 继续贴底；
  * 3. 非贴底 + 数据变化（前插历史、删除）→ 按锚点恢复位置，避免画面跳动；
  *    纯「测量回填」（totalSize 变但消息引用没变）不干预 scrollTop，避免打断手动拖动。

package/dist/types/components/chat-messages/use-virtual-list.d.ts

@@ -1,4 +1,5 @@
 import { RefObject } from 'preact';
+import { ReadonlySignal, Signal } from '@preact/signals';
 
 /**
  * 虚拟列表项
@@ -100,6 +101,36 @@ export interface UseVirtualListResult {
      * @memberof UseVirtualListResult
      */
     restoreScrollPosition: () => void;
+    /**
+     * 响应式总高度：依赖测量版本号（实测高度回填）与条数，供自定义滚动条订阅
+     *
+     * @type {ReadonlySignal<number>}
+     */
+    totalSizeSignal: ReadonlySignal<number>;
+    /**
+     * 容器 scrollTop 信号（供自定义滚动条计算 thumb 位置）
+     *
+     * @type {Signal<number>}
+     */
+    scrollTopSignal: Signal<number>;
+    /**
+     * 容器可视高度信号
+     *
+     * @type {Signal<number>}
+     */
+    clientHeightSignal: Signal<number>;
+    /**
+     * 自定义滚动条拖动状态：拖动中跳过头部前插的 scrollTop 补偿，由滚动条按指针比例重映射接管
+     *
+     * @type {Signal<boolean>}
+     */
+    isDragging: Signal<boolean>;
+    /**
+     * 程序化设置滚动位置：同步 scrollTop 信号 + 直接写容器 scrollTop（clamp 到当前可滚动范围）
+     *
+     * @type {(top: number) => void}
+     */
+    setScrollTop: (top: number) => void;
 }
 /**
  * 动态高度虚拟列表 Hook

package/dist/types/components/chat-net-disk/chat-net-disk.d.ts

@@ -0,0 +1,7 @@
+import { AiChatController } from '../../controller';
+
+interface ChatNetDiskProps {
+    controller: AiChatController;
+}
+export declare const ChatNetDisk: (props: ChatNetDiskProps) => import("preact").JSX.Element;
+export {};

package/dist/types/components/chat-scrollbar/chat-scrollbar.d.ts

@@ -0,0 +1,102 @@
+import { RefObject } from 'preact';
+import { ReadonlySignal, Signal } from '@preact/signals';
+
+export interface ChatScrollbarProps {
+    /**
+     * 滚动容器 ref（与 useVirtualList 的 containerRef 同源）
+     *
+     * @type {RefObject<HTMLDivElement | null>}
+     */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /**
+     * 容器 scrollTop 信号
+     *
+     * @type {Signal<number>}
+     */
+    scrollTop: Signal<number>;
+    /**
+     * 容器可视高度信号
+     *
+     * @type {Signal<number>}
+     */
+    clientHeight: Signal<number>;
+    /**
+     * 内容总高度信号（依赖实测高度回填）
+     *
+     * @type {ReadonlySignal<number>}
+     */
+    totalSize: ReadonlySignal<number>;
+    /**
+     * 程序化写滚动位置（同步信号 + 写容器 scrollTop）
+     *
+     * @type {(top: number) => void}
+     */
+    setScrollTop: (top: number) => void;
+    /**
+     * 拖动到顶部附近的通知（触发加载更早历史）
+     *
+     * 拖到顶部且前插补偿被跳过时，scrollTop 值可能不变导致浏览器不派发 scroll 事件，
+     * 因此不能只依赖 scroll 事件，需在此处直接通知
+     *
+     * @type {() => void}
+     */
+    onNearTop?: () => void;
+    /**
+     * 拖动状态回调（父组件转发给 useVirtualList 的 setIsDragging）
+     *
+     * @type {(dragging: boolean) => void}
+     */
+    onDragStateChange?: (dragging: boolean) => void;
+    /**
+     * thumb 最小高度，避免内容过长时不可抓取
+     *
+     * @type {number}
+     */
+    minThumbSize?: number;
+}
+/**
+ * 自定义虚拟滚动条
+ *
+ * ## 为什么不用原生滚动条
+ * 动态高度虚拟列表中未测量的项用预估高度占位，快速拖动原生滚动条时新项不断被实测，
+ * totalSize（scrollHeight）持续变化，原生 thumb 按比例重定位导致滚动条乱跳。
+ *
+ * ## 核心策略
+ * 隐藏原生滚动条绘制，保留原生 scrollTop 驱动内容（wheel/键盘/触摸不变），自绘 thumb：
+ * - 拖动期间 thumb 定位用指针比例（dragRatio），不依赖异步的 scroll 事件回读，无滞后抖动；
+ * - 拖动期间 totalSize 变化（测量回填/历史前插）时，按指针比例重映射 scrollTop，
+ *   thumb 始终钉在指针下方，内容坐标系在其下方重排。
+ *
+ * ## 与 useVirtualList 的数据流交联
+ * 本组件不持有滚动状态，全部通过 props 注入 useVirtualList 暴露的信号与回调，
+ * 二者是「显示层 ↔ 驱动层」的关系：
+ *
+ * ```
+ * useVirtualList                          ChatScrollbar
+ * ────────────                          ──────────────
+ * totalSizeSignal ─────────────────────► totalSize     （thumb 高度/比例）
+ * clientHeightSignal ──────────────────► clientHeight  （thumb 高度/比例）
+ * scrollTopSignal ─────────────────────► scrollTop     （非拖动期 thumb 位置）
+ * setScrollTop ◄──────────────────────── 拖动/翻页      （程序化写滚动位置）
+ * onDragStateChange ──► isDragging ──► 前插补偿跳过
+ * onNearTop ──────────────────────────► 加载更早历史
+ * ```
+ *
+ * 正向（useVirtualList → 本组件）：
+ * - 滚动/测量回填/历史前插 → totalSize、scrollTop 信号变化 → 本组件重渲染更新 thumb；
+ * - totalSizeSignal 是懒求值信号（只依赖测量版本号），滚动过程中零额外计算。
+ *
+ * 反向（本组件 → useVirtualList）：
+ * - 拖动/点击翻页 → setScrollTop：同步写 scrollTop 信号 + 写容器 DOM，
+ *   信号先行避免下一帧用旧值闪跳；虚拟列表据此重算可视区；
+ * - onDragStateChange → 虚拟列表的 isDragging 信号置 true：
+ *   拖动期间「头部前插补偿」被跳过（use-virtual-list.ts:373），
+ *   前插导致的 totalSize 变化改由本组件的重锚定 effect 按指针比例重映射 scrollTop 接管，
+ *   两端不会同时争抢滚动位置；
+ * - onNearTop：拖到顶部时直接通知父级加载历史——前插补偿被跳过后 scrollTop 可能不变，
+ *   浏览器不派发 scroll 事件，不能只依赖滚动事件触发加载。
+ *
+ * @author zpc
+ * @date 2026-10-12
+ */
+export declare const ChatScrollbar: (props: ChatScrollbarProps) => import("preact").JSX.Element | null;

package/dist/types/components/common/breadcrumb/breadcrumb.d.ts

@@ -0,0 +1,16 @@
+
+interface BreadcrumbProps {
+    /**
+     * 当前路径（根 -> 当前层）
+     */
+    path: {
+        id: string;
+        label: string;
+    }[];
+    /**
+     * 点击某一层跳转，-1 表示回到根
+     */
+    onJump: (index: number) => void;
+}
+export declare const Breadcrumb: (props: BreadcrumbProps) => import("preact").JSX.Element;
+export {};

package/dist/types/components/common/lazy-list-tree/lazy-list-tree.d.ts

@@ -0,0 +1,59 @@
+import { LazyTreeNode } from '../lazy-tree/lazy-tree';
+
+interface LazyListTreeProps {
+    /**
+     * 根节点数据
+     */
+    nodes: LazyTreeNode[];
+    /**
+     * 异步加载子节点方法
+     * 返回子节点数组
+     */
+    lazyLoad?: (node: LazyTreeNode) => Promise<LazyTreeNode[]>;
+    /**
+     * 节点选中回调
+     */
+    onNodeCheck?: (node: LazyTreeNode, checked: boolean) => void;
+    /**
+     * 节点点击回调
+     */
+    onNodeClick?: (node: LazyTreeNode, event: MouseEvent) => void;
+    /**
+     * 节点展开回调
+     */
+    onNodeExpand?: (node: LazyTreeNode, expanded: boolean) => void;
+    /**
+     * 路径变化回调，用于父组件同步面包屑
+     */
+    onPathChange?: (path: LazyTreeNode[]) => void;
+    /**
+     * 受控路径（根 -> 当前层），由父组件传入
+     */
+    path?: LazyTreeNode[];
+    /**
+     * 是否显示搜索框
+     */
+    showSearch?: boolean;
+    /**
+     * 默认选中keys
+     */
+    defaultCheckedKeys?: string[];
+    /**
+     * 高亮选中
+     */
+    highlight?: boolean;
+    /**
+     * 标识分隔符
+     */
+    separator?: string;
+    /**
+     * 过滤值
+     */
+    filter?: string;
+    /**
+     * 是否可拖拽
+     */
+    draggable?: boolean;
+}
+export declare const LazyListTree: (props: LazyListTreeProps) => import("preact").JSX.Element;
+export {};

package/dist/types/components/common/lazy-tree/lazy-tree.d.ts

@@ -40,8 +40,12 @@ export interface LazyTreeNode {
      * 自定义图标
      */
     icon?: string;
+    /**
+     * 原始数据
+     */
+    data: Record<string, any>;
 }
-export interface LazyTreeProps {
+interface LazyTreeProps {
     /**
      * 根节点数据
      */
@@ -63,6 +67,14 @@ export interface LazyTreeProps {
      * 节点展开回调
      */
     onNodeExpand?: (node: LazyTreeNode, expanded: boolean) => void;
+    /**
+     * 当前活动路径变化回调（用户最后点击/展开的路径）
+     */
+    onActivePathChange?: (path: LazyTreeNode[]) => void;
+    /**
+     * 当前激活路径
+     */
+    activePath?: LazyTreeNode[];
     /**
      * 是否显示搜索框
      */
@@ -75,6 +87,10 @@ export interface LazyTreeProps {
      * 高亮选中
      */
     highlight?: boolean;
+    /**
+     * 高亮选中父节点
+     */
+    highlightParent?: boolean;
     /**
      * 是否在点击节点的时候展开或者收缩节点
      */
@@ -83,6 +99,14 @@ export interface LazyTreeProps {
      * 标识分隔符
      */
     separator?: string;
+    /**
+     * 过滤值
+     */
+    filter?: string;
+    /**
+     * 是否可拖拽
+     */
+    draggable?: boolean;
 }
 /**
  * 懒加载树组件
@@ -90,3 +114,4 @@ export interface LazyTreeProps {
  * 具有懒加载、搜索、展开折叠等功能
  */
 export declare const LazyTree: (props: LazyTreeProps) => import("preact").JSX.Element;
+export {};

package/dist/types/components/flat-chat-container/flat-chat-container.d.ts

@@ -1,6 +1,7 @@
 import { Component, RefObject, JSX } from 'preact';
 import { Namespace } from '../../utils';
 import { AiChatController, AiTopicController } from '../../controller';
+import { AiActionPanelController } from '../../controller/ai-action-panel/ai-action-panel.controller';
 import { IChatToolbarItem, IExtensionOptions } from '../../interface';
 
 export interface FlatChatContainerProps {
@@ -54,6 +55,12 @@ export interface FlatChatContainerProps {
      * @memberof FlatChatContainerProps
      */
     extension?: IExtensionOptions;
+    /**
+     * @description 操作区面板控制器
+     * @type {AiActionPanelController}
+     * @memberof FlatChatContainerProps
+     */
+    actionPanel?: AiActionPanelController;
 }
 interface FlatContainerContext {
     enableBackFill: boolean;
@@ -92,6 +99,14 @@ export declare class FlatChatContainer extends Component<FlatChatContainerProps>
      * 输入区高度拖动时其父容器高度(px)
      */
     inputDragContainerHeight: number;
+    /**
+     * 操作区面板上一帧显示状态（用于 componentDidUpdate 边沿检测）
+     */
+    private panelVisiblePrev;
+    /**
+     * 操作区面板宽度拖动起始值(px)
+     */
+    private panelDragStartWidth;
     state: {
         mountedSlots: Record<string, boolean>;
         inputHeight: number | null;
@@ -116,6 +131,11 @@ export declare class FlatChatContainer extends Component<FlatChatContainerProps>
      * @memberof FlatChatContainer
      */
     componentDidUpdate(prevProps: FlatChatContainerProps): void;
+    /**
+     * @description 同步操作区面板状态（展开收起动画由 CSS 过渡完成）
+     * @memberof FlatChatContainer
+     */
+    syncPanelState(): void;
     /**
      * @description 异步挂载扩展插槽
      * @private
@@ -153,6 +173,19 @@ export declare class FlatChatContainer extends Component<FlatChatContainerProps>
      * 侧栏宽度拖动结束
      */
     handleSidebarResizeEnd: () => void;
+    /**
+     * 操作区面板宽度拖动开始
+     */
+    handlePanelResizeStart: () => void;
+    /**
+     * 操作区面板宽度拖动中
+     * - 向左拖：主内容区变窄、面板变宽；向右拖反之
+     */
+    handlePanelResizeMove: (delta: number) => void;
+    /**
+     * 操作区面板宽度拖动结束（持久化）
+     */
+    handlePanelResizeEnd: () => void;
     /**
      * @description 获取输入区高度缓存key
      * @returns {string}
@@ -189,6 +222,12 @@ export declare class FlatChatContainer extends Component<FlatChatContainerProps>
      * @memberof FlatChatContainer
      */
     renderHeader(): JSX.Element;
+    /**
+     * @description 绘制右侧操作区（含分隔条）
+     * - DOM 常驻，宽度随 visible 切换由 CSS 过渡展开/收起
+     * @memberof FlatChatContainer
+     */
+    renderActionRegion(): JSX.Element | null;
     render(): JSX.Element;
 }
 export {};

package/dist/types/components/index.d.ts

@@ -1,4 +1,5 @@
 export { ChatContainer } from './chat-container/chat-container';
 export { FlatChatContainer } from './flat-chat-container/flat-chat-container';
+export { ChatActionPanel } from './chat-action-panel/chat-action-panel';
 export { SimpleChatContainer } from './simple-chat-container/simple-chat-container';
 export { ChatQuesition } from './chat-quesition/chat-quesition';

package/dist/types/constants/index.d.ts

@@ -18,6 +18,14 @@ export declare enum AIChatConst {
      * 聊天输入区高度缓存
      */
     INPUT_HEIGHT = "ai-chat-input-height",
+    /**
+     * 操作区面板宽度缓存
+     */
+    ACTION_PANEL_WIDTH = "ai-chat-action-panel-width",
+    /**
+     * 操作区面板默认宽度(px)
+     */
+    ACTION_PANEL_DEFAULT_WIDTH = 380,
     /**
      * 数据库名称
      */

package/dist/types/controller/ai-action-panel/ai-action-panel.controller.d.ts

@@ -0,0 +1,102 @@
+import { Signal } from '@preact/signals';
+import { TActionPanelComponent } from '../../interface';
+
+/**
+ * 将操作区面板宽度校正到合理区间 [最小宽度, 容器宽度/3]
+ *
+ * @param {number} width 目标宽度
+ * @param {number} containerWidth 容器整体宽度
+ * @returns {*} {number}
+ */
+export declare function clampPanelWidth(width: number, containerWidth: number): number;
+/**
+ * 操作区面板控制器
+ * - 面板为容器级单例，挂在 ChatBaseController 上，切话题不重建
+ * - 展开收起动画由容器 CSS 过渡完成，控制器不参与
+ *
+ * @export
+ * @class AiActionPanelController
+ */
+export declare class AiActionPanelController {
+    /**
+     * 面板是否显示
+     */
+    readonly visible: Signal<boolean>;
+    /**
+     * 面板当前宽度(px)
+     */
+    readonly width: Signal<number>;
+    /**
+     * 面板标题
+     */
+    readonly caption: Signal<string>;
+    /**
+     * 面板内容组件
+     */
+    readonly component: Signal<TActionPanelComponent | undefined>;
+    /**
+     * 内容组件额外参数
+     */
+    readonly params: Signal<Record<string, any> | undefined>;
+    /**
+     * 组件外层容器id（用于宽度缓存隔离）
+     */
+    private compWrapperId;
+    /**
+     * 打开操作区面板
+     * - 已打开时仅替换标题、内容组件与额外参数
+     * - 首次打开时从缓存恢复面板宽度（无缓存则沿用当前值）
+     *
+     * @param {string} caption 标题
+     * @param {TActionPanelComponent} component 内容组件
+     * @param {Record<string, any>} [params] 额外参数（作为内容组件props传入）
+     * @memberof AiActionPanelController
+     */
+    open(caption: string, component: TActionPanelComponent, params?: Record<string, any>): void;
+    /**
+     * 关闭操作区面板（收起动画由容器 CSS 过渡完成）
+     *
+     * @memberof AiActionPanelController
+     */
+    close(): void;
+    /**
+     * 更新面板宽度
+     *
+     * @param {number} px 宽度(px)
+     * @memberof AiActionPanelController
+     */
+    updateWidth(px: number): void;
+    /**
+     * 提交当前宽度（持久化）
+     *
+     * @memberof AiActionPanelController
+     */
+    commitWidth(): void;
+    /**
+     * 注入组件外层容器id
+     *
+     * @param {string} id
+     * @memberof AiActionPanelController
+     */
+    injectCompWrapperId(id: string): void;
+    /**
+     * 读取宽度缓存
+     *
+     * @returns {*} {(number | undefined)}
+     * @memberof AiActionPanelController
+     */
+    readWidthCache(): number | undefined;
+    /**
+     * 重置全部状态（整个聊天窗口关闭时调用）
+     *
+     * @memberof AiActionPanelController
+     */
+    reset(): void;
+    /**
+     * 获取宽度缓存key
+     *
+     * @returns {string}
+     * @memberof AiActionPanelController
+     */
+    private getCacheKey;
+}