@ibiz-template-plugin/ai-chat 0.0.119 → 0.0.120

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

@@ -166,6 +166,10 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
      * @memberof ChatContainer
      */
     private interactable;
+    /**
+     * resize 节流句柄
+     */
+    private resizeRafId;
     /**
      * 消息完成事件回调
      */
@@ -174,6 +178,19 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
      * 最小化状态变化事件回调
      */
     private onMinimizeChangeHandler;
+    /**
+     * 浏览器窗口尺寸变化处理
+     * - 触发节流后统一重算：容器最小宽高、左侧栏宽度、右侧面板宽度
+     */
+    private handleWindowResize;
+    /**
+     * 浏览器窗口尺寸变化后的重算逻辑
+     * 1. 校正窗口自身尺寸，不低于最小宽高，且不超出可视区域
+     * 2. 收敛左侧栏宽度到 [左最小宽, 容器宽 - 中最小宽 - 右占用]
+     * 3. 收敛右侧面板宽度到 [右最小宽, 容器宽 - 中最小宽 - 左占用]
+     * 4. 同步输入区高度，保证消息区最小高
+     */
+    private recalcOnResize;
     listener(): void;
     componentDidUpdate(): void;
     /**
@@ -382,6 +399,7 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
     getRightWidth(): string;
     /**
      * @description 获取宽度
+     * @private
      * @returns {*}  {{
      *     centreMinWidth: number;
      *     leftWidth: number;
@@ -391,13 +409,7 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
      *   }}
      * @memberof ChatContainer
      */
-    getWidth(): {
-        centreMinWidth: number;
-        leftWidth: number;
-        rightWidth: number;
-        leftMinWidth: number;
-        rightMinWidth: number;
-    };
+    private getWidth;
     /**
      * 侧栏宽度拖动开始
      */
@@ -411,7 +423,7 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
      */
     handleSidebarResizeEnd: () => void;
     /**
-     * 将侧栏宽度校正到合理区间 [200, 容器宽度/3, 容器宽度-右侧最小宽]
+     * 将侧栏宽度校正到合理区间 [最小宽, 容器宽度-右侧最小宽]
      */
     clampSidebarWidth(width: number): number;
     /**
@@ -460,6 +472,11 @@ export declare class ChatContainer extends Component<ChatContainerProps, ChatCon
      * 提交拖动边框后的输入区高度（持久化到状态与本地缓存）
      */
     commitInputHeight: () => void;
+    /**
+     * 将面板宽度矫正到合理区间 [最小宽, 容器宽度-左侧最小宽]
+     * @param width
+     */
+    clampPanelWidth(width: number): void;
     /**
      * 操作区面板宽度拖动开始
      */

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

@@ -22,6 +22,13 @@ interface FileNewPanelProps {
         ok: boolean;
         data: LazyTreeNode;
     }) => void;
+    /**
+     * @description 后缀名
+     * @default '.txt'
+     * @type {string}
+     * @memberof FileNewPanelProps
+     */
+    suffixName?: string;
 }
 export declare const FileNewPanel: (props: FileNewPanelProps) => import("preact").JSX.Element;
 export {};

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

@@ -8,7 +8,7 @@ interface BreadcrumbProps {
         label: string;
     }[];
     /**
-     * 点击某一层跳转，-1 表示回到根
+     * 点击某一层跳转
      */
     onJump: (index: number) => void;
 }

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

@@ -5,7 +5,7 @@ export { Slider } from './slider/slider';
 export { Switch } from './switch/switch';
 export { Actions, type IAction } from './actions/actions';
 export { Breadcrumb } from './breadcrumb/breadcrumb';
-export { LazyListTree, type LazyListTreeRef, type LazyListTreeMode, } from './lazy-list-tree/lazy-list-tree';
+export { LazyLevelList, type LazyLevelListRef, type LazyLevelListMode, } from './lazy-level-list/lazy-level-list';
 export { ContextMenu, type IContextMenuAction, } from './context-menu/context-menu';
 export { Drawer } from './drawer/drawer';
 export { LazyTree, type LazyTreeRef, type LazyTreeNode, type INodeEditInfo, } from './lazy-tree/lazy-tree';

package/dist/types/components/common/{lazy-list-tree/lazy-list-tree.d.ts → lazy-level-list/lazy-level-list.d.ts}

@@ -1,8 +1,8 @@
 import { INodeEditInfo, LazyTreeNode } from '../lazy-tree/lazy-tree';
 import { IAction } from '../actions/actions';
 
-export type LazyListTreeMode = 'list' | 'card';
-interface LazyListTreeProps {
+export type LazyLevelListMode = 'list' | 'card';
+interface LazyLevelListProps {
     /**
      * 根节点数据
      */
@@ -83,17 +83,17 @@ interface LazyListTreeProps {
      * 展示模式
      * @default 'list'
      */
-    mode?: LazyListTreeMode;
+    mode?: LazyLevelListMode;
 }
-export interface LazyListTreeRef {
+export interface LazyLevelListRef {
     /**
      * 重载
      * @param
      * @returns
      */
-    overloadNode: () => Promise<void>;
+    overloadNode: (node: LazyTreeNode) => Promise<void>;
 }
-export declare const LazyListTree: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<LazyListTreeProps> & {
-    ref?: import('preact').Ref<LazyListTreeRef> | undefined;
+export declare const LazyLevelList: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<LazyLevelListProps> & {
+    ref?: import('preact').Ref<LazyLevelListRef> | undefined;
 }>;
 export {};

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

@@ -54,6 +54,10 @@ export interface LazyTreeNode {
      * 根节点
      */
     isRoot?: boolean;
+    /**
+     * 是否显示
+     */
+    visible?: boolean;
 }
 export interface INodeEditInfo {
     /**

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

@@ -112,10 +112,42 @@ export declare class FlatChatContainer extends Component<FlatChatContainerProps>
      * 操作区面板宽度拖动起始值(px)
      */
     private panelDragStartWidth;
+    /**
+     * resize 节流句柄
+     */
+    private resizeRafId;
     state: {
         mountedSlots: Record<string, boolean>;
         inputHeight: number | null;
     };
+    /**
+     * @description 获取宽度
+     * @private
+     * @returns {*}  {{
+     *     centreMinWidth: number;
+     *     leftWidth: number;
+     *     rightWidth: number;
+     *     leftMinWidth: number;
+     *     rightMinWidth: number;
+     *   }}
+     * @memberof FlatChatContainer
+     */
+    private getWidth;
+    /**
+     * 浏览器窗口尺寸变化处理
+     * - 触发节流后统一重算：容器最小宽高、左侧栏宽度、右侧面板宽度
+     */
+    private handleWindowResize;
+    /**
+     * @description 浏览器窗口尺寸变化后的重算逻辑
+     * 1. 收敛左侧栏宽度到 [左最小宽, 容器宽 - 中最小宽 - 右占用]
+     * 2. 收敛右侧面板宽度到 [右最小宽, 容器宽 - 中最小宽 - 左占用]
+     * 3. 同步输入区高度，保证消息区最小高
+     * @private
+     * @returns {*}  {void}
+     * @memberof FlatChatContainer
+     */
+    private recalcOnResize;
     /**
      * @description 添加扩展插槽
      * @private
@@ -131,11 +163,24 @@ export declare class FlatChatContainer extends Component<FlatChatContainerProps>
      * @memberof FlatChatContainer
      */
     componentDidMount(): void;
+    /**
+     * @description 销毁
+     * @memberof FlatChatContainer
+     */
+    componentWillUnmount(): void;
     /**
      * @description 更新
      * @memberof FlatChatContainer
      */
     componentDidUpdate(prevProps: FlatChatContainerProps): void;
+    /**
+     * 拖动容器边框时实时校正输入区高度，保证消息区不小于最小高度
+     */
+    syncInputHeight: () => void;
+    /**
+     * 提交拖动边框后的输入区高度（持久化到状态与本地缓存）
+     */
+    commitInputHeight: () => void;
     /**
      * @description 同步操作区面板状态（展开收起动画由 CSS 过渡完成）
      * @memberof FlatChatContainer
@@ -166,6 +211,10 @@ export declare class FlatChatContainer extends Component<FlatChatContainerProps>
      * 右侧聊天区宽度
      */
     getRightWidth(): string;
+    /**
+     * 将侧栏宽度校正到合理区间 [最小宽, 容器宽度-右侧最小宽]
+     */
+    clampSidebarWidth(width: number): number;
     /**
      * 侧栏宽度拖动开始
      */
@@ -178,6 +227,11 @@ export declare class FlatChatContainer extends Component<FlatChatContainerProps>
      * 侧栏宽度拖动结束
      */
     handleSidebarResizeEnd: () => void;
+    /**
+     * 将面板宽度矫正到合理区间 [最小宽, 容器宽度-左侧最小宽]
+     * @param width
+     */
+    clampPanelWidth(width: number): void;
     /**
      * 操作区面板宽度拖动开始
      */

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

@@ -6,7 +6,7 @@ interface ActionItem {
     caption: string;
     icon?: VNode;
 }
-export declare const Popup: ({ triggerMode, children, actions, content, position, isOpen: isOpenProp, onToggleOpen, popupClassName, onAction, }: {
+export declare const Popup: ({ triggerMode, children, actions, content, disabled, position, isOpen: isOpenProp, onToggleOpen, popupClassName, onAction, }: {
     triggerMode: "click" | "hover";
     children: import('preact').ComponentChildren;
     actions?: ActionItem[];
@@ -14,6 +14,7 @@ export declare const Popup: ({ triggerMode, children, actions, content, position
     position?: Position;
     isOpen?: boolean;
     popupClassName?: string;
+    disabled?: boolean;
     onToggleOpen?: (isOpen: boolean) => void;
     onAction?: (actionId: string, event: MouseEvent) => void;
 }) => import("preact").JSX.Element;

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

@@ -1,14 +1,6 @@
 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 上，切话题不重建

package/dist/types/controller/file-system/file-system.controller.d.ts

@@ -1,4 +1,4 @@
-import { IFile, IFileItem, IMessageUtil, IFileItemParams, IFileUploadPrams, IFileSystemOptions, FileUploaderOptions } from '../../interface';
+import { IFile, IFileItem, IMessageUtil, IConfirmUtil, IFileItemParams, IFileUploadPrams, IFileSystemOptions, FileUploaderOptions } from '../../interface';
 import { AiChatController } from '../ai-chat/ai-chat.controller';
 
 /**
@@ -38,6 +38,13 @@ export declare class FileSystemController {
      * @memberof FileSystemController
      */
     get message(): IMessageUtil | undefined;
+    /**
+     * @description 提示
+     * @readonly
+     * @type {(IConfirmUtil | undefined)}
+     * @memberof FileSystemController
+     */
+    get confirm(): IConfirmUtil | undefined;
     /**
      * @description 文件预览模式
      * @readonly
@@ -66,12 +73,12 @@ export declare class FileSystemController {
      */
     fetch(params: IFileItemParams): Promise<IFileItem | undefined>;
     /**
-     * @description 文件上传
+     * @description 系统文件上传
      * @param {IFileUploadPrams} params
      * @returns {*}  {(Promise<IFile | undefined>)}
      * @memberof FileSystemController
      */
-    uploadFile(params: IFileUploadPrams): Promise<IFile | undefined>;
+    uploadSystemFile(params: IFileUploadPrams): Promise<IFile | undefined>;
     /**
      * @description 获取文件内容
      * @param {string} id
@@ -149,4 +156,20 @@ export declare class FileSystemController {
      * @memberof FileSystemController
      */
     delete(file_path: string): Promise<boolean>;
+    /**
+     * @description 选择文件
+     * @param {string} [accept='']
+     * @param {boolean} [multiple=false]
+     * @returns {*}  {(Promise<FileList | undefined>)}
+     * @memberof FileSystemController
+     */
+    selectFile(accept?: string, multiple?: boolean): Promise<FileList | undefined>;
+    /**
+     * @description 上传文件到系统
+     * @param {string} file_path 文件路径
+     * @param {File} file 文件
+     * @returns {*}  {Promise<void>}
+     * @memberof FileSystemController
+     */
+    uploadFileToSystem(file_path: string, file: File): Promise<boolean>;
 }

package/dist/types/interface/i-file-system-options/i-file-system-options.d.ts

@@ -23,6 +23,19 @@ interface IFileSystemUploadParams {
     srfaiagent?: string;
     srfscope?: string;
 }
+/**
+ * @description 下载文件参数
+ * @interface IFileSystemDownLoadParams
+ */
+interface IFileSystemDownLoadParams {
+    sessionid: string;
+    folder: string;
+    id: string;
+    file_path: string;
+    srfaiagent?: string;
+    srfscope?: string;
+    timeout?: number;
+}
 /**
  * @description 新建目录参数
  * @interface IFileSystemCreateParams
@@ -143,6 +156,11 @@ export interface IFileSystemOptions {
         name: string;
         folder: string;
     } | undefined>;
+    /**
+     * @description 下载文件
+     * @memberof IFileSystemOptions
+     */
+    downloadFile: (ctx: object, param: object, other: IFileSystemDownLoadParams) => Promise<IFileSystemResult>;
     /**
      * @description 获取文件内容
      * @param {object} ctx

package/dist/types/locale/en/index.d.ts

@@ -180,4 +180,5 @@ export declare const EN: {
     uploadFile: string;
     fileContent: string;
     clear: string;
+    fileExists: string;
 };

package/dist/types/locale/zh-CN/index.d.ts

@@ -180,4 +180,5 @@ export declare const ZH_CN: {
     uploadFile: string;
     fileContent: string;
     clear: string;
+    fileExists: string;
 };

package/docs/msglist-memory-optimization.md

@@ -0,0 +1,90 @@
+# 消息列表内存优化：视口外占位回收（msglist-memory-optimization）
+
+> 记录本次「聊天消息列表内存暴增/崩溃」优化的背景、方案演进与现行实现机制，供后续新增任务与 bug 修复参考。
+> 涉及文件：`src/components/chat-message-item/chat-message-item.tsx`（核心）、`markdown-message.tsx` / `user-message.tsx` / `error-message.tsx`（配套 Cherry 清理）。
+
+## 1. 背景：为什么内存会崩溃
+
+- 消息正文由 Cherry Markdown 渲染，每个实例内含 CodeMirror、解析器、事件监听器，**单实例内存开销大**。
+- 原方案「渐进真实绘制 + 绘制过永久留 DOM」（`chat-messages.tsx`）：初始绘制最新 20 条，向上滚动逐批扩展，**绘制过的消息永久真实渲染**。
+- 结果：长会话从头滚到尾后，所有消息的 Cherry 实例常驻内存，内存随滚动单调增长，最终崩溃。
+
+## 2. 方案演进（均已验证并放弃，勿恢复）
+
+| 方案 | 放弃原因 |
+| --- | --- |
+| 自研虚拟列表（绝对定位 + spacer） | 滚动条抖动严重 |
+| react-virtuoso | 滚动条乱滚/抖动 |
+| 列表级 IO 驱动 + 估算参与（rAF 队列/距离排序/renderStartIndex 收窄） | 复杂度高，滚动条抖动未解决，被有意推翻 |
+| 估算高度占位 | 高度失准导致滚动条跳动 |
+| 图片 lazy 加载 | 加载后撑高导致占位失准 |
+| CSS `content-visibility: auto` | 只跳过渲染不卸载 DOM，Cherry/CodeMirror 内存无法释放，不解决根本问题 |
+
+**现行方案**：渐进渲染（列表级，管「从未绘制的更早历史」）+ item 级实测高度占位（管「绘制过但离开视口的消息」），两层互补，`chat-messages.tsx` / `use-message-renderer.ts` 不做改动。
+
+## 3. 现行机制：item 级「实测高度占位 + 双缓冲过渡」
+
+全部逻辑在 `ChatMessageItem` 内自管理（`chat-message-item.tsx`）。
+
+### 3.1 状态
+
+| 状态 | 实现 | 说明 |
+| --- | --- | --- |
+| `height` | `useSignal(0)` | 高度缓存：RO 持续写入组件实际外高（小数），随图片加载/Cherry 异步渲染同步更新 |
+| `phase` | `useSignal<Phase>('real')` | `real`（真实绘制）/ `placeholder`（占位）/ `transition`（双缓冲过渡） |
+| `isWaitingRef` | `useRef` | 流式标记，IO 回调闭包经它读取，避免持有过期 message |
+
+### 3.2 阶段流转
+
+```
+                 ┌──────────────────────────────────────────────┐
+                 │  IO isIntersecting=true                      │
+   ┌──────┐      │  (占位继续锚定，真实组件隐藏重挂)   ┌────┐    │
+   │ real │──────┼─────────────────────────────────▶ │占位 │◀───┼── IO isIntersecting=false
+   └──────┘      ▼                                   └────┘    │   （iswaiting/height=0 不占位）
+             transition ── RO 实测隐藏中的真实组件：             ▲
+                 │        ├ 高度≈缓存(≤0.5px) ──▶ 切 real      │
+                 │        └ 不一致且稳定 100ms ──▶ 接受新高度切 real（只动一次滚动条）
+                 └── 滚走可随时中断回 placeholder
+```
+
+- **real → placeholder**：滚出视口（150% 缓冲带外）→ 卸载真实组件（Cherry destroy 释放内存）→ 渲染 `height` 精确高度的占位 div。
+- **placeholder → transition**：进入视口 → 占位**继续留在文档流锚定 scrollHeight**，真实组件以 `absolute + visibility: hidden` 隐藏重挂（不影响布局）。
+- **transition → real**：RO 实测隐藏真实组件，高度与缓存一致（差 ≤ `HEIGHT_EPSILON`=0.5px）立即切换；不一致则无 RO 事件稳定 `SETTLE_DELAY`=100ms 后接受新高度（内容真实变化时只动一次滚动条）。
+
+**为什么需要双缓冲**：直接占位→真实重挂载时，内容重建（Cherry 异步初始化、代码高亮重跑、图片重新解码）会产生高度瞬变，`scrollHeight` 反复变化 → 滚动条跳动。双缓冲下过渡全程 scrollHeight 零变化。
+
+### 3.3 关键实现细节（改代码前必读）
+
+1. **观察目标分工**：IO 观察稳定的 wrapper（`containerRef`，含 `id=messageid`，永不重挂）；RO 观察真实组件容器（`realRef`，transition 期间是隐藏的 absolute 元素）。
+2. **测高用 `borderBoxSize[0].blockSize`**：占位 div 直接替换真实组件容器，高度必须与元素**外高**完全一致；`contentBox`/`clientHeight` 会漏掉 padding 导致漂移。
+3. **wrapper `minHeight + boxSizing: 'content-box'` 锁定**：挡住真实绘制阶段的「变矮」瞬变；显式 content-box 防宿主应用全局 border-box 重置（否则 min-height 会多算 wrapper 上下 6px padding）。用 min-height 而非 height：视口内正常长高（图片、流式）仍能跟随。
+4. **`position: relative` 仅在 transition 期间设置**：真实阶段 wrapper 无定位，工具栏弹层的定位基准不变（避免影响既有弹层行为）。
+5. **IO 配置**：`root=null`（视口）——intersectionRect 会被中间滚动容器裁剪，滚出容器即不相交，组件自包含、多聊天实例可用；`rootMargin: '150% 0px'` 提供缓冲带减少切换频率。
+6. **三类守卫**（缺一不可）：
+   - `el.offsetParent === null`：容器隐藏（keep-alive 失活）忽略 IO 事件，激活后 IO 自动重估；
+   - `iswaiting === true`：流式消息高度持续增长，不占位；
+   - `height <= 0`：未实测过高度不占位（真实渲染至少一次才有占位资格）。
+7. **Cherry destroy 清理**（占位回收释放内存的前提，勿删）：`markdown-message.tsx` / `user-message.tsx` / `error-message.tsx` 卸载时 `cherry.destroy()`，`deep-research-result.tsx:218` 已有。Cherry 均为单实例守卫（有实例则 `setMarkdown`），无重复创建泄漏。
+
+### 3.4 与 chat-messages（列表层）的关系
+
+- 列表层的渐进渲染（初始 20 条 + 逐帧切片 + 触顶加载历史）、贴底判定、keep-alive 恢复**全部未动**。
+- 消息首次被渐进渲染纳入 → item 挂载实测高度 → 滚出视口自动被 item 占位回收 → 再次进入视口经 transition 恢复。
+- 话题切换：messages 清空重载，item 卸载重建，item 内状态（height/phase）自然重置。
+
+## 4. 已知边界与注意事项（新增任务/修 bug 指引）
+
+1. **transition 兜底路径的瞬变风险**：若重挂后内容迟迟不渲染（如 Cherry 初始化阻塞 >100ms 且期间无布局变化触发 RO），settle 定时器会接受「中间态小高度」，内容渲染完成后再一次长高 → 单次跳动。概率低；若实测出现，调大 `SETTLE_DELAY`（150~200ms）或在 settle 接受时要求 `boxHeight > 0`。
+2. **不要引入**：估算高度占位、图片 lazy、绝对定位虚拟列表、手动 scrollTop 补偿——均已被实测否决（见第 2 节）。
+3. **不要删除**：wrapper 的 minHeight 锁定、transition 双缓冲、三类守卫、Cherry destroy——滚动条稳定性与内存回收都依赖它们。
+4. **占位回收会卸载 ChatToolbar**（children 随真实组件卸载），视口外工具栏状态不保留；如需保留状态需提升到 controller 层。
+5. **tsc 已知既有错误**：`chat-message-item.tsx` 的 TS2769（`h(com, ...)` 联合类型）在优化前就存在（HEAD 同样报错），仓库多处历史类型错误导致 `pnpm build` 失败，与本次改动无关；本文件 eslint 通过。
+6. **`vite.config.ts` 的 `isDebug=true`** 为本地调试构建配置（sourcemap/不压缩/preserveModules），**不要随功能一起提交**。
+
+## 5. 验证清单（改动后回归）
+
+1. **内存**：长会话来回滚动一遍 → DevTools Performance Monitor 内存曲线有界；heap snapshot 无 Cherry/CodeMirror 残留实例。
+2. **滚动条稳定**：快速拖动滚动条，占位↔真实切换全程 thumb 无跳动/闪动。
+3. **内容填充**：快速拖动经过区域 0.5s 内填满，无长时间空白。
+4. **回归**：贴底跟随、发送消息强制贴底、流式输出不占位、回到底部按钮、keep-alive 失活/激活恢复、话题切换、向上滚动渐进扩展与历史加载。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibiz-template-plugin/ai-chat",
-  "version": "0.0.119",
+  "version": "0.0.120",
   "description": "iBiz AI交互框插件",
   "type": "module",
   "main": "dist/index.es.js",