From 55908f7b8f7936bb8b4cd9e1b584a94abe1c3989 Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Sun, 5 Oct 2025 06:39:58 +0800
Subject: [PATCH] bugfix

---
 aidocs/accordion.md            | 205 +++++++++
 aidocs/aggrid.md               | 226 ++++++++++
 aidocs/asr.md                  | 220 +++++++++
 aidocs/audio.md                | 404 +++++++++++++++++
 aidocs/bar.md                  | 211 +++++++++
 aidocs/binstreaming.md         | 276 ++++++++++++
 aidocs/bricks.md               | 498 +++++++++++++++++++++
 aidocs/button.md               | 254 +++++++++++
 aidocs/camera.md               | 355 +++++++++++++++
 aidocs/cols.md                 | 323 ++++++++++++++
 aidocs/conform.md              | 249 +++++++++++
 aidocs/continueaudio.md        | 314 +++++++++++++
 aidocs/countdown.md            | 284 ++++++++++++
 aidocs/css.md                  |  88 ++++
 aidocs/datagrid.md             | 434 ++++++++++++++++++
 aidocs/datarow.md              | 311 +++++++++++++
 aidocs/dataviewer.md           | 502 +++++++++++++++++++++
 aidocs/docxviewer.md           | 262 +++++++++++
 aidocs/dynamicaccordion.md     | 399 +++++++++++++++++
 aidocs/dynamiccolumn.md        | 173 ++++++++
 aidocs/echartsext.md           | 301 +++++++++++++
 aidocs/factory.md              | 162 +++++++
 aidocs/floaticonbar.md         | 321 ++++++++++++++
 aidocs/form.md                 | 353 +++++++++++++++
 aidocs/gobang.md               | 283 ++++++++++++
 aidocs/html.md                 | 123 ++++++
 aidocs/i18n.md                 | 283 ++++++++++++
 aidocs/iconbarpage.md          | 218 +++++++++
 aidocs/iframe.md               | 184 ++++++++
 aidocs/image.md                | 350 +++++++++++++++
 aidocs/input.md                | 621 ++++++++++++++++++++++++++
 aidocs/jsoncall.md             | 391 ++++++++++++++++
 aidocs/keypress.md             | 126 ++++++
 aidocs/layout.md               | 359 +++++++++++++++
 aidocs/line.md                 | 203 +++++++++
 aidocs/llm.md                  | 414 +++++++++++++++++
 aidocs/llm_dialog.md           | 366 +++++++++++++++
 aidocs/llmout.md               | 297 +++++++++++++
 aidocs/markdown_viewer.md      | 250 +++++++++++
 aidocs/menu.md                 | 367 +++++++++++++++
 aidocs/message.md              | 218 +++++++++
 aidocs/miniform.md             | 314 +++++++++++++
 aidocs/modal.md                | 295 ++++++++++++
 aidocs/multiple_state_image.md | 170 +++++++
 aidocs/myoperator.md           | 117 +++++
 aidocs/myvad.md                | 164 +++++++
 aidocs/page_data_loader.md     | 317 +++++++++++++
 aidocs/paging.md               | 272 ++++++++++++
 aidocs/period.md               | 322 ++++++++++++++
 aidocs/pie.md                  | 257 +++++++++++
 aidocs/popup.md                | 502 +++++++++++++++++++++
 aidocs/progressbar.md          | 150 +++++++
 aidocs/qaframe.md              | 343 ++++++++++++++
 aidocs/recorder.md             | 410 +++++++++++++++++
 aidocs/registerfunction.md     | 183 ++++++++
 aidocs/rtc.md                  | 435 ++++++++++++++++++
 aidocs/running.md              | 198 +++++++++
 aidocs/scroll.md               | 293 ++++++++++++
 aidocs/splitter.md             | 139 ++++++
 aidocs/streaming_audio.md      | 240 ++++++++++
 aidocs/svg.md                  | 350 +++++++++++++++
 aidocs/tab.md                  | 334 ++++++++++++++
 aidocs/tabular.md              | 304 +++++++++++++
 aidocs/toolbar.md              | 368 +++++++++++++++
 aidocs/tree.md                 | 356 +++++++++++++++
 aidocs/tree_choose.md          | 106 +++++
 aidocs/uitype.md               | 274 ++++++++++++
 aidocs/uitypesdef.md           | 428 ++++++++++++++++++
 aidocs/utils.md                | 787 +++++++++++++++++++++++++++++++++
 aidocs/vadtext.md              | 268 +++++++++++
 aidocs/video.md                | 292 ++++++++++++
 aidocs/videoplayer.md          | 398 +++++++++++++++++
 aidocs/views.md                | 176 ++++++++
 aidocs/vision.md               |  90 ++++
 aidocs/websocket.md            | 254 +++++++++++
 aidocs/webspeech.md            | 240 ++++++++++
 aidocs/widget.md               | 499 +++++++++++++++++++++
 aidocs/wsllm.md                | 427 ++++++++++++++++++
 aidocs/wterm.md                | 347 +++++++++++++++
 79 files changed, 23597 insertions(+)
 create mode 100644 aidocs/accordion.md
 create mode 100644 aidocs/aggrid.md
 create mode 100644 aidocs/asr.md
 create mode 100644 aidocs/audio.md
 create mode 100644 aidocs/bar.md
 create mode 100644 aidocs/binstreaming.md
 create mode 100644 aidocs/bricks.md
 create mode 100644 aidocs/button.md
 create mode 100644 aidocs/camera.md
 create mode 100644 aidocs/cols.md
 create mode 100644 aidocs/conform.md
 create mode 100644 aidocs/continueaudio.md
 create mode 100644 aidocs/countdown.md
 create mode 100644 aidocs/css.md
 create mode 100644 aidocs/datagrid.md
 create mode 100644 aidocs/datarow.md
 create mode 100644 aidocs/dataviewer.md
 create mode 100644 aidocs/docxviewer.md
 create mode 100644 aidocs/dynamicaccordion.md
 create mode 100644 aidocs/dynamiccolumn.md
 create mode 100644 aidocs/echartsext.md
 create mode 100644 aidocs/factory.md
 create mode 100644 aidocs/floaticonbar.md
 create mode 100644 aidocs/form.md
 create mode 100644 aidocs/gobang.md
 create mode 100644 aidocs/html.md
 create mode 100644 aidocs/i18n.md
 create mode 100644 aidocs/iconbarpage.md
 create mode 100644 aidocs/iframe.md
 create mode 100644 aidocs/image.md
 create mode 100644 aidocs/input.md
 create mode 100644 aidocs/jsoncall.md
 create mode 100644 aidocs/keypress.md
 create mode 100644 aidocs/layout.md
 create mode 100644 aidocs/line.md
 create mode 100644 aidocs/llm.md
 create mode 100644 aidocs/llm_dialog.md
 create mode 100644 aidocs/llmout.md
 create mode 100644 aidocs/markdown_viewer.md
 create mode 100644 aidocs/menu.md
 create mode 100644 aidocs/message.md
 create mode 100644 aidocs/miniform.md
 create mode 100644 aidocs/modal.md
 create mode 100644 aidocs/multiple_state_image.md
 create mode 100644 aidocs/myoperator.md
 create mode 100644 aidocs/myvad.md
 create mode 100644 aidocs/page_data_loader.md
 create mode 100644 aidocs/paging.md
 create mode 100644 aidocs/period.md
 create mode 100644 aidocs/pie.md
 create mode 100644 aidocs/popup.md
 create mode 100644 aidocs/progressbar.md
 create mode 100644 aidocs/qaframe.md
 create mode 100644 aidocs/recorder.md
 create mode 100644 aidocs/registerfunction.md
 create mode 100644 aidocs/rtc.md
 create mode 100644 aidocs/running.md
 create mode 100644 aidocs/scroll.md
 create mode 100644 aidocs/splitter.md
 create mode 100644 aidocs/streaming_audio.md
 create mode 100644 aidocs/svg.md
 create mode 100644 aidocs/tab.md
 create mode 100644 aidocs/tabular.md
 create mode 100644 aidocs/toolbar.md
 create mode 100644 aidocs/tree.md
 create mode 100644 aidocs/tree_choose.md
 create mode 100644 aidocs/uitype.md
 create mode 100644 aidocs/uitypesdef.md
 create mode 100644 aidocs/utils.md
 create mode 100644 aidocs/vadtext.md
 create mode 100644 aidocs/video.md
 create mode 100644 aidocs/videoplayer.md
 create mode 100644 aidocs/views.md
 create mode 100644 aidocs/vision.md
 create mode 100644 aidocs/websocket.md
 create mode 100644 aidocs/webspeech.md
 create mode 100644 aidocs/widget.md
 create mode 100644 aidocs/wsllm.md
 create mode 100644 aidocs/wterm.md

diff --git a/aidocs/accordion.md b/aidocs/accordion.md
new file mode 100644
index 0000000..689b064
--- /dev/null
+++ b/aidocs/accordion.md
@@ -0,0 +1,205 @@
+# `bricks.Accordion` 技术文档
+
+```markdown
+# bricks.Accordion
+
+`bricks.Accordion` 是一个基于 `bricks.VBox` 的可折叠面板组件，允许用户通过点击标题按钮切换显示不同的内容区域。常用于需要节省垂直空间、分组展示信息的界面设计中。
+
+---
+
+## 继承关系
+
+- **继承自**: `bricks.VBox`
+- **注册名称**: `'Accordion'`（通过 `bricks.Factory.register` 注册）
+
+---
+
+## 构造函数
+
+### `new bricks.Accordion(opts)`
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `opts` | Object | 配置选项对象 |
+
+#### `opts` 配置项
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `item_size` | String | `'25px'` | 每个标题项的高度（CSS 尺寸字符串） |
+| `item_css` | String | `'accordion-button'` | 标题按钮使用的 CSS 类名 |
+| `content_css` | String | `'accordion-content'` | 内容区域使用的 CSS 类名 |
+| `items` | Array\<Object\> | 必填 | 要显示的面板项列表 |
+
+##### `items` 数组元素结构
+
+每个 `item` 是一个对象，包含以下字段：
+
+| 字段 | 类型 | 是否必需 | 说明 |
+|------|------|----------|------|
+| `name` | String | 是 | 唯一标识符，用于定位和缓存内容 |
+| `icon` | String | 否 | 显示在按钮前的图标类名（如 Font Awesome 类） |
+| `label` | String | 是 | 按钮上显示的文本标签 |
+| `content` | Object | 是 | 描述子组件的配置对象（符合 `widgetBuild` 结构） |
+| `refresh` | Boolean | 否 | 若为 `true`，每次点击都会重新构建内容（不使用缓存） |
+
+---
+
+## 成员属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `w_items` | Array\<bricks.Button\> | 存储所有标题按钮实例的数组 |
+| `subcontents` | Object | 缓存已创建的内容组件，键为 `name`，值为对应的 widget 实例 |
+| `content` | bricks.Filler | 包裹内容区域的容器 |
+| `sub_container` | bricks.VScrollPanel | 实际承载内容的可滚动面板 |
+| `key_select_items` | Array | 支持键盘导航的选择项集合（用于上下键选择） |
+| `keyselectable` | Boolean | `true`，表示该组件支持键盘选择操作 |
+
+---
+
+## 方法
+
+### `constructor(opts)`
+
+初始化 Accordion 组件：
+
+1. 调用父类构造函数。
+2. 设置整体高度为 `100%`。
+3. 创建多个 `bricks.Button` 实例作为标题栏，并绑定 `click` 事件到 `change_content`。
+4. 初始化内容显示区域（`VScrollPanel`）并插入第一个项目的内容。
+
+> ⚠️ 注意：第一个按钮会自动触发一次 `click` 事件以加载默认内容。
+
+---
+
+### `async change_content(event)`
+
+处理标题按钮点击事件，动态切换显示内容。
+
+#### 参数
+
+- `event`: DOM 事件对象，`event.target.bricks_widget` 应指向被点击的 `bricks.Button` 实例。
+
+#### 行为逻辑
+
+1. 获取被点击按钮的 `name`。
+2. 在 `this.opts.items` 中查找对应项的位置与配置。
+3. 判断是否需要刷新：
+   - 如果设置了 `refresh: true`
+   - 或者该内容尚未被缓存
+4. 若需刷新或未缓存，则调用 `bricks.widgetBuild()` 异步生成新内容并缓存。
+5. 清空当前内容区，并将新内容添加进 `sub_container`。
+6. 更新布局：移除旧的 `content` widget 并重新插入（确保位于正确位置）。
+
+#### 错误处理
+
+- 若找不到匹配的 `name`，会在控制台输出警告日志。
+- 若 `item.content` 不存在，则打印错误信息并返回。
+
+---
+
+## 事件绑定
+
+- 所有标题按钮均监听 `click` 事件，触发 `change_content` 回调。
+- 使用 `.bind(this)` 确保回调中的 `this` 指向正确的 Accordion 实例。
+
+---
+
+## 示例配置
+
+```javascript
+var accordion = new bricks.Accordion({
+  item_size: '30px',
+  item_css: 'my-accordion-button',
+  content_css: 'my-accordion-content',
+  items: [
+    {
+      name: 'general',
+      icon: 'fa fa-home',
+      label: '通用设置',
+      content: {
+        widgettype: 'TextBlock',
+        text: '这里是通用设置内容...'
+      }
+    },
+    {
+      name: 'advanced',
+      icon: 'fa fa-cog',
+      label: '高级选项',
+      refresh: true,
+      content: {
+        widgettype: 'FormPanel',
+        fields: [ ... ]
+      }
+    }
+  ]
+});
+```
+
+---
+
+## 样式建议（CSS）
+
+```css
+.accordion-button {
+  padding: 8px 12px;
+  background-color: #f0f0f0;
+  border-bottom: 1px solid #ddd;
+  cursor: pointer;
+  font-weight: bold;
+}
+
+.accordion-button:hover {
+  background-color: #e0e0e0;
+}
+
+.accordion-content {
+  padding: 10px;
+  background-color: #fff;
+  border: 1px solid #ddd;
+  min-height: 100px;
+}
+```
+
+> 可根据实际需求覆盖默认类名或通过 `item_css` / `content_css` 自定义。
+
+---
+
+## 工厂注册
+
+```javascript
+bricks.Factory.register('Accordion', bricks.Accordion);
+```
+
+允许通过工厂方法创建实例：
+
+```javascript
+bricks.widgetBuild({ widgettype: 'Accordion', ... });
+```
+
+---
+
+## 注意事项
+
+- 内容组件是**懒加载**的，仅在首次点击时创建。
+- 支持**缓存机制**，避免重复渲染提升性能；可通过 `refresh: true` 强制重载。
+- 支持键盘导航（上下箭头选择按钮），前提是容器环境支持焦点管理。
+- `widgetBuild` 返回的是 `Promise`，因此 `change_content` 定义为 `async` 函数。
+
+---
+
+## 调试信息
+
+启用调试模式后，点击按钮时会输出类似日志：
+
+```text
+accordion: button= [Button Instance] name= general
+```
+
+可通过 `bricks.debug()` 控制开关。
+
+---
+```
\ No newline at end of file
diff --git a/aidocs/aggrid.md b/aidocs/aggrid.md
new file mode 100644
index 0000000..1647ae8
--- /dev/null
+++ b/aidocs/aggrid.md
@@ -0,0 +1,226 @@
+# `bricks.AG_Grid` 技术文档
+
+> 基于 [ag-Grid](https://www.ag-grid.com/) 封装的可复用 JavaScript 网格组件，继承自 `bricks.JsWidget`。
+
+---
+
+## 概述
+
+`bricks.AG_Grid` 是一个基于 `ag-Grid` 的封装类，用于在网页中快速创建功能丰富的数据表格。它支持从远程 URL 动态加载数据，并提供列定义、排序、过滤、多选、单元格点击事件等基础功能。
+
+该类继承自 `bricks.JsWidget`，遵循统一的组件初始化和生命周期管理机制。
+
+---
+
+## 依赖
+
+- `ag-Grid`（必须全局可用，即 `agGrid` 对象已加载）
+- `bricks.js` 核心库（包含 `bricks.JsWidget` 基类）
+
+---
+
+## 构造函数
+
+```js
+new bricks.AG_Grid(options)
+```
+
+### 参数
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `options` | `Object` | ✅ | 配置选项对象 |
+
+#### `options` 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `dataurl` | `String` | ✅ | - | 数据接口 URL，返回 JSON 格式数组数据 |
+| `fields` | `Array<Object>` | ✅ | - | 列字段配置列表，每个字段包含显示信息 |
+
+##### `fields` 字段配置项
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `name` | `String` | ✅ | - | 字段名（对应数据中的 key） |
+| `label` | `String` | ❌ | `name` | 表头显示名称 |
+| `width` | `Number` | ❌ | `100` | 列宽度（像素） |
+
+---
+
+## 类定义
+
+```js
+var bricks = window.bricks || {};
+bricks.AG_Grid = class extends bricks.JsWidget {
+    /* 
+        opts 示例：
+        {
+            dataurl: "/api/data",
+            fields: [
+                { name: "id", label: "ID", width: 80 },
+                { name: "name", label: "姓名" },
+                { name: "age", width: 60 }
+            ]
+        }
+    */
+    
+    constructor(opts) {
+        super(opts);
+        this.ag_opts = {}; // ag-Grid 配置对象
+    }
+
+    init() {
+        // 初始化数据源
+        this.datasource = {
+            getRows: this.getRows.bind(this),
+            startRow: 0
+        };
+
+        // 设置 ag-Grid 配置项
+        this.ag_opts.columnDefs = [];
+        this.ag_opts.rowModelType = 'infinite';
+        this.ag_opts.maxConcurrentDatasourceRequests = 1;
+        this.ag_opts.datasource = this.datasource;
+        
+        // 生成列定义
+        for (let i = 0; i < this.opts.fields.length; i++) {
+            const field = this.opts.fields[i];
+            const colDef = {
+                field: field.name,
+                headerName: field.label || field.name,
+                width: field.width || 100
+            };
+            this.ag_opts.columnDefs.push(colDef);
+        }
+
+        // 默认列行为：可排序、可过滤
+        this.ag_opts.defaultColDef = { sortable: true, filter: true };
+        
+        // 启用多行选择
+        this.ag_opts.rowSelection = 'multiple';
+        
+        // 启用行动画效果
+        this.ag_opts.animateRows = true;
+
+        // 绑定单元格点击事件
+        this.ag_opts.onCellClicked = this.cell_clicked.bind(this);
+
+        // 初始化 ag-Grid 实例
+        this.aggrid = new agGrid.Grid(this.dom_element, this.ag_opts);
+
+        // 加载初始数据（一次性加载全部）
+        fetch(this.opts.dataurl)
+            .then(response => response.json())
+            .then(data => {
+                this.ag_opts.api.setRowData(data); // 注意：此处与 infinite model 不符，见下方说明
+            })
+            .catch(err => console.error('Failed to load data:', err));
+    }
+
+    cell_clicked(params) {
+        bricks.debug('Cell clicked:', params);
+    }
+}
+```
+
+---
+
+## 方法说明
+
+### `constructor(opts)`
+
+调用父类构造函数并初始化 `this.ag_opts` 为空对象，用于后续存储 ag-Grid 配置。
+
+### `init()`
+
+组件初始化主逻辑：
+
+1. 定义 `datasource` 对象（为无限滚动做准备，但当前实现未完全使用）。
+2. 遍历 `opts.fields` 构建 `columnDefs`。
+3. 设置通用表格行为（排序、过滤、多选、动画）。
+4. 创建 `ag-Grid` 实例并与 DOM 元素绑定。
+5. 使用 `fetch` 请求 `dataurl` 获取初始数据，并通过 `setRowData` 填充表格。
+
+> ⚠️ **注意**：虽然设置了 `rowModelType: 'infinite'`，但实际并未正确实现 `getRows` 方法，因此当前行为更像是“客户端模型”，而非真正的无限滚动。建议根据需求调整数据加载方式。
+
+### `cell_clicked(params)`
+
+单元格点击回调函数，输出调试信息到控制台（需 `bricks.debug` 存在）。
+
+参数 `params` 包含：
+- `value`: 当前单元格值
+- `column`: 列对象
+- `rowIndex`: 行索引
+- `data`: 整行数据对象
+- 更多详见 [ag-Grid 官方文档](https://www.ag-grid.com/javascript-data-grid/cell-events/)
+
+---
+
+## 使用示例
+
+```html
+<div id="myGrid" style="height: 400px;" class="ag-theme-alpine"></div>
+
+<script>
+new bricks.AG_Grid({
+    dom_element: document.getElementById('myGrid'),
+    dataurl: '/api/users',
+    fields: [
+        { name: 'id', label: '用户ID', width: 80 },
+        { name: 'name', label: '姓名', width: 120 },
+        { name: 'email', label: '邮箱' },
+        { name: 'age', label: '年龄', width: 60 }
+    ]
+});
+</script>
+```
+
+---
+
+## 已知问题与改进建议
+
+| 问题 | 说明 | 建议 |
+|------|------|------|
+| `getRows` 未实现 | `datasource.getRows` 未定义，却赋值给了 `this.datasource.getRows` | 若使用 `infinite` 模式，应实现分页加载逻辑 |
+| `startRow` 未绑定上下文 | `startRow` 在 `datasource` 中未正确定义为属性 | 应作为闭包变量或实例属性维护 |
+| `setRowData` 不适用于 Infinite Model | `setRowData` 仅适用于客户端模型 | 改为调用 `api.setDatasource()` 并完整实现 `getRows` |
+| 错误语法 | `maxConcurrentDatasourceRequests: 1,` 使用了冒号而非赋值 | 应为 `=` |
+| `width` 和 `label` 的默认值写法错误 | 使用了位运算符 `|` 而非逻辑默认值 | 应使用 `||` 或 `??` |
+
+### 修正建议代码片段
+
+```js
+// 正确的字段处理
+width: field.width ?? 100,
+headerName: field.label ?? field.name,
+
+// 正确的属性赋值
+this.ag_opts.maxConcurrentDatasourceRequests = 1;
+
+// 实现 getRows（若启用 infinite 模式）
+getRows(params) {
+    fetch(`${this.opts.dataurl}?start=${params.startRow}&end=${params.endRow}`)
+        .then(res => res.json())
+        .then(data => {
+            params.successCallback(data, data.length === 100 ? 10000 : data.length);
+        });
+}
+```
+
+---
+
+## 总结
+
+`bricks.AG_Grid` 提供了一个简洁的 ag-Grid 封装，适合快速集成静态或小规模动态数据表格。但在大数据场景下需完善 `infinite` 模式的数据源实现以提升性能。
+
+建议后续优化方向：
+- 完整支持分页/无限滚动
+- 支持列类型、渲染器扩展
+- 添加加载状态提示
+- 支持外部刷新方法
+
+--- 
+
+📌 **版本**: 1.0  
+📅 **最后更新**: 2025-04
\ No newline at end of file
diff --git a/aidocs/asr.md b/aidocs/asr.md
new file mode 100644
index 0000000..962743f
--- /dev/null
+++ b/aidocs/asr.md
@@ -0,0 +1,220 @@
+# `bricks.ASRClient` 技术文档
+
+> 基于 WebSocket 的语音识别客户端组件，用于实时音频流传输与文本识别结果接收。
+
+---
+
+## 概述
+
+`bricks.ASRClient` 是一个基于 `bricks.VBox` 的类，封装了浏览器端的语音识别功能。它通过调用 Web Audio API 获取用户麦克风输入，并使用 WebSocket 将音频数据以 Base64 编码形式发送至后端 ASR（自动语音识别）服务。同时监听服务器返回的识别结果，并触发相应事件。
+
+该组件提供了一个可点击的图标按钮来控制录音的开始与停止，支持自定义图标、WebSocket 地址和附加参数。
+
+---
+
+## 继承关系
+
+- **继承自**：`bricks.VBox`
+- **注册名称**：`ASRClient`（可通过 `bricks.Factory.create('ASRClient', options)` 创建）
+
+```js
+bricks.Factory.register('ASRClient', bricks.ASRClient);
+```
+
+---
+
+## 构造函数
+
+### `constructor(opts)`
+
+#### 参数
+
+| 参数名         | 类型     | 说明 |
+|----------------|----------|------|
+| `opts`         | Object   | 配置选项对象，见下表 |
+
+##### `opts` 配置项
+
+| 属性名         | 类型     | 默认值 | 说明 |
+|----------------|----------|--------|------|
+| `start_icon`   | String   | `'imgs/start_recording.svg'` | 开始录音时显示的图标路径（SVG/PNG） |
+| `stop_icon`    | String   | `'imgs/stop_recording.svg'`  | 停止录音时显示的图标路径（SVG/PNG） |
+| `ws_url`       | String   | 必填   | WebSocket 服务器地址，例如：`wss://asr.example.com/ws` |
+| `icon_options` | Object   | `{}`   | 传递给内部 `bricks.Svg` 图标组件的额外配置 |
+| `ws_params`    | Object   | `{}`   | 发送至 WebSocket 服务的附加参数，在每次发送音频时合并使用 |
+
+---
+
+## 事件
+
+`ASRClient` 支持以下自定义事件，可通过 `.bind()` 方法监听：
+
+| 事件名       | 触发时机                     | 参数格式（`event.params`） |
+|--------------|------------------------------|----------------------------|
+| `start`      | 用户点击开始录音             | 无参数                     |
+| `stop`       | 用户点击停止录音             | 无参数                     |
+| `transtext`  | 接收到服务器返回的识别文本   | `{ content, speaker, start, end }` |
+
+示例：
+```js
+asr.bind('transtext', function(e) {
+    console.log('识别结果:', e.params.content);
+});
+```
+
+---
+
+## 属性
+
+| 属性名        | 类型          | 说明 |
+|---------------|---------------|------|
+| `status`      | String        | 当前状态：`'start'` 或 `'stop'` |
+| `icon`        | `bricks.Svg`  | 控制按钮图标实例 |
+| `socket`      | `WebSocket`   | 连接到 ASR 服务的 WebSocket 实例 |
+| `stream`      | `MediaStream` | 来自 `getUserMedia` 的音频流 |
+| `mediaRecorder` | `MediaRecorder` | 浏览器原生媒体录制对象，每秒收集并发送音频块 |
+
+---
+
+## 方法
+
+### `toggle_button()`
+
+切换录音状态（开始 ↔ 停止），并更新按钮图标。
+
+- 若当前为 `'stop'`，则切换为 `'start'` 并调用 `start_recording()`
+- 若当前为 `'start'`，则切换为 `'stop'` 并调用 `stop_recording()`
+
+绑定在图标的 `click` 事件上。
+
+---
+
+### `async start_recording()`
+
+启动麦克风录音并开始向服务器发送音频数据。
+
+#### 行为流程：
+
+1. 调用 `navigator.mediaDevices.getUserMedia({ audio: true })` 请求麦克风权限。
+2. 创建 `MediaRecorder` 实例处理音频流。
+3. 设置 `ondataavailable` 回调：每 1 秒生成一段音频 Blob。
+4. 使用 `blobToBase64()` 工具将 Blob 转为 Base64 字符串。
+5. 构造消息体并发送至 WebSocket 服务器：
+    ```json
+    {
+      "type": "audiobuffer",
+      "data": "base64string...",
+      ...ws_params
+    }
+    ```
+
+> ⚠️ 注意：需确保页面运行在 HTTPS 环境或本地开发环境（localhost），否则无法获取麦克风权限。
+
+---
+
+### `stop_recording()`
+
+停止 `MediaRecorder` 录音，关闭音频流轨道。
+
+```js
+this.mediaRecorder.stop();
+// 同时会释放麦克风资源
+```
+
+---
+
+### `response_data(event)`
+
+处理来自 WebSocket 的服务器响应。
+
+#### 参数
+
+- `event.data`: 服务器返回的 JSON 字符串
+
+#### 动作
+
+1. 解析 JSON 数据
+2. 触发 `transtext` 事件并将解析后的数据作为参数分发
+
+```js
+this.dispatch('transtext', parsedData);
+```
+
+---
+
+### `response_log(event)`
+
+调试方法：将接收到的识别结果输出到控制台。
+
+```js
+console.log('response data=', event.params);
+```
+
+可通过重写此方法实现日志收集或 UI 更新。
+
+---
+
+## 内部依赖
+
+| 工具/函数           | 说明 |
+|----------------------|------|
+| `bricks_resource(path)` | 解析资源路径的工具函数，通常用于构建静态资源 URL |
+| `blobToBase64(blob)`    | 异步将 Blob 转换为 Base64 编码字符串 |
+| `objcopy(obj)`          | 深拷贝对象（防止修改原始 `ws_params`） |
+
+> 示例 `blobToBase64` 实现：
+> ```js
+> function blobToBase64(blob) {
+>   return new Promise((resolve, reject) => {
+>     const reader = new FileReader();
+>     reader.onload = () => resolve(reader.result.split(',')[1]);
+>     reader.onerror = reject;
+>     reader.readAsDataURL(blob);
+>   });
+> }
+> ```
+
+---
+
+## 使用示例
+
+```js
+var asr = new bricks.ASRClient({
+    ws_url: 'wss://your-asr-server.com/asr',
+    start_icon: 'imgs/mic-on.svg',
+    stop_icon: 'imgs/mic-off.svg',
+    ws_params: {
+        lang: 'zh-CN',
+        model: 'conversational'
+    }
+});
+
+// 监听识别结果
+asr.bind('transtext', function(e) {
+    document.getElementById('output').innerHTML += '<p>' + e.params.content + '</p>';
+});
+
+// 插入到 DOM 容器
+document.body.appendChild(asr.render());
+```
+
+---
+
+## 注意事项
+
+1. **安全性要求**：必须在安全上下文（HTTPS 或 localhost）中运行才能访问麦克风。
+2. **浏览器兼容性**：需要支持 `MediaRecorder` API 和 `WebSocket`。
+3. **性能建议**：每秒发送一次音频块，避免频繁请求；建议使用 Opus 编码压缩音频。
+4. **错误处理**：未对 `getUserMedia` 失败做降级处理，建议外层捕获异常。
+
+---
+
+## 版本信息
+
+- **作者**：Bricks Framework Team
+- **版本**：1.0
+- **最后更新**：2025年4月5日
+
+--- 
+
+📌 *文档结束*
\ No newline at end of file
diff --git a/aidocs/audio.md b/aidocs/audio.md
new file mode 100644
index 0000000..7f850ac
--- /dev/null
+++ b/aidocs/audio.md
@@ -0,0 +1,404 @@
+# `bricks` 音频模块技术文档
+
+本文档为 `bricks` 框架中的音频相关功能模块提供详细说明，包含以下核心类：
+
+- `bricks.formatMs()` —— 时间格式化工具函数
+- `bricks.AudioPlayer` —— 音频播放器组件
+- `bricks.AudioRecorder` —— 音频录制与上传组件
+- `bricks.TextedAudioPlayer` —— 带文本同步的流式音频播放器
+- 工厂注册机制（通过 `bricks.Factory`）
+
+---
+
+## 1. 工具函数：`bricks.formatMs(ms, all)`
+
+将毫秒数转换为可读的时间字符串，支持自定义显示粒度。
+
+### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `ms` | `number` | 时间（单位：毫秒） |
+| `all` | `boolean?` | 是否强制显示所有时间单位（即使高位为0） |
+
+### 返回值
+
+返回格式化的字符串，形式如：`"h:mm:ss″sss"` 或 `"mm:ss″sss"`
+
+- 小时部分仅在非零时显示
+- 分钟和秒根据上下文决定是否显示前导零
+- 毫秒固定三位数字补全
+
+### 示例
+
+```js
+bricks.formatMs(3661234);     // 输出: "1:01:01″234"
+bricks.formatMs(61234, true); // 输出: "01:01″0234"
+```
+
+---
+
+## 2. 音频播放器：`bricks.AudioPlayer`
+
+基于 HTML5 `<audio>` 元素封装的高级音频播放控制组件。
+
+### 继承关系
+
+```js
+class AudioPlayer extends bricks.JsWidget
+```
+
+### 构造选项 (`options`)
+
+| 属性 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `url` | `string` | 否 | `null` | 初始音频源 URL |
+| `autoplay` | `boolean` | 否 | `false` | 是否自动播放 |
+
+### 实例属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `audio` | `HTMLAudioElement` | 内部使用的 `<audio>` DOM 节点 |
+| `source` | `HTMLSourceElement` | 动态创建的 `<source>` 节点 |
+| `playlist` | `Array<string>` | 待播放的 URL 列表（队列） |
+| `url_generator` | `AsyncGenerator` | 流式加载 URL 的异步生成器 |
+| `srcList` | `Array<{played: boolean, url: string}>` | 动态加载的音频源列表 |
+
+### 方法
+
+#### `get_status() → string`
+
+获取当前播放状态。
+
+**返回值：**
+
+| 状态 | 说明 |
+|------|------|
+| `"error"` | 音频加载出错 |
+| `"ended"` | 播放结束 |
+| `"paused"` | 暂停中 |
+| `"loading"` | 数据不足，正在缓冲 |
+| `"playing"` | 正在播放 |
+
+---
+
+#### `add_url(url: string)`
+
+向播放队列添加新音频。若当前状态为 `'error'` 或 `'ended'`，立即播放该音频；否则加入队列。
+
+---
+
+#### `set_source(url: string)`
+
+设置音频源并更新 DOM。
+
+> ⚠️ 注意：会同时设置 `this.audio.src` 和内部 `<source>` 元素。
+
+---
+
+#### `set_stream_urls(response: Response)`
+
+从服务器流式接收多个音频 URL（每行一个），用于连续播放场景（如语音合成流）。
+
+##### 参数
+
+- `response`: `fetch` 返回的 `Response` 对象，其 body 应为逐行输出的文本流。
+
+##### 实现逻辑
+
+1. 创建异步生成器 `dyn_urls()` 解析流数据。
+2. 使用 `schedule_once()` 异步启动 `load_queue_url()`。
+3. 自动预加载并顺序播放音频片段。
+
+---
+
+#### `async load_queue_url()`
+
+内部方法：持续从 `url_generator` 获取新的音频 URL，并维护 `srcList`。
+
+当 `srcList.length < 2` 时触发首次播放。
+
+---
+
+#### `async play_srclist(event?)`
+
+播放 `srcList` 中尚未播放的第一个音频项。
+
+- 若传入事件对象且音频未结束，则不执行。
+- 播放完成后通过 `'ended'` 事件继续下一首。
+
+---
+
+#### `play()` / `toggle_play()`
+
+- `play()`: 异步调用原生 `audio.play()`。
+- `toggle_play()`: 切换播放/暂停状态。
+
+---
+
+#### `set_url(url)` 
+
+设置音频源并立即开始播放。
+
+等价于：
+```js
+this.set_source(url);
+this.audio.play();
+```
+
+---
+
+## 3. 音频录制器：`bricks.AudioRecorder`
+
+实现麦克风录音、可视化、文件上传与下载功能。
+
+### 外部依赖
+
+必须引入第三方库 [Recorder.js](https://gitee.com/xiangyuecn/Recorder)，支持 WAV 格式录音。
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/recorder-js"></script>
+```
+
+### 继承关系
+
+```js
+class AudioRecorder extends bricks.HBox
+```
+
+### 构造选项 (`opts`)
+
+| 属性 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `upload_url` | `string` | 否 | `null` | 录音结束后上传的目标地址 |
+| `start_icon` | `string` | 否 | 内置 SVG | 开始按钮图标路径 |
+| `stop_icon` | `string` | 否 | 内置 SVG | 停止按钮图标路径 |
+| `icon_rate` | `number` | 否 | `undefined` | 图标缩放比例 |
+
+### 事件系统
+
+通过 `this.dispatch()` 触发以下自定义事件：
+
+| 事件名 | 触发时机 | 携带参数 |
+|--------|----------|---------|
+| `record_started` | 开始录音 | 无 |
+| `record_ended` | 结束录音 | `{data: Blob, url: string, duration: number}` |
+| `uploaded` | 成功上传后 | 服务器返回结果 |
+
+可通过 `bind()` 监听这些事件。
+
+### 主要组件
+
+- `rec_btn`: 使用 `bricks.Svg` 显示切换式按钮（开始/停止）
+- `rec_time`: 显示已录制时长（调用 `bricks.formatMs()`）
+- `wave`: （预留）波形图显示区域（需额外包支持）
+
+### 核心方法
+
+#### `recOpen()` / `recClose()`
+
+打开或关闭麦克风权限。
+
+- 调用 `Recorder.open()` 请求用户授权。
+- 成功后设置 `this.rec` 实例并派发 `record_started`。
+- 失败时打印调试信息。
+
+---
+
+#### `start_recording()` / `stop_recording()`
+
+开始或停止录音。
+
+- `start_recording`: 若已授权则直接开始，否则先调用 `recOpen()`。
+- `stop_recording`: 调用 `rec.stop()` 获取 `Blob` 和时长，生成本地 URL 并派发 `record_ended`。
+
+---
+
+#### `on_process(buffers, powerLevel, ...)` 
+
+录音过程中的实时回调（约每秒12次）。
+
+当前用途：
+- 更新录音时长显示（`bufferDuration`）
+- 可扩展用于绘制音量条或波形图（注释中示例）
+
+---
+
+#### `upload() → Promise<void>`
+
+将录音文件以 `FormData` 形式上传至 `upload_url`。
+
+使用 `bricks.jpost()` 发送请求，附带运行中提示（`bricks.Running`）。
+
+成功后派发 `uploaded` 事件。
+
+---
+
+#### `download()`
+
+触发浏览器下载当前录音文件（WAV 格式），文件名为 `recorder-{timestamp}.wav`。
+
+> ⚠️ 下载完成后自动释放 `ObjectURL` 防止内存泄漏。
+
+---
+
+## 4. 文本同步音频播放器：`bricks.TextedAudioPlayer`
+
+专为“语音+字幕”场景设计的垂直布局播放器，支持流式 JSON 数据驱动。
+
+### 继承关系
+
+```js
+class TextedAudioPlayer extends bricks.VBox
+```
+
+### 组件结构
+
+- 上方：`AudioPlayer` 控件
+- 下方：`VScrollPanel` 包含 `Text` 组件用于显示文本内容
+
+### 核心特性
+
+支持通过流式响应动态加载语音与对应文本，实现边生成边播放的效果（适用于 TTS + 字幕同步）。
+
+### 方法
+
+#### `set_stream_urls(response: Response)`
+
+解析流式 JSON 响应，每一行为一个 `{audio: base64, text: string}` 对象。
+
+使用辅助函数 `streamResponseJson(response, callback)` 逐条处理。
+
+---
+
+#### `load_stream_data(json)`
+
+接收到单条流数据后的处理逻辑：
+
+1. 存入 `streaming_buffer` 队列；
+2. 若当前空闲（`wait_play === true`），立即触发 `playnext()`。
+
+---
+
+#### `playnext()`
+
+从缓冲区取出下一条数据：
+
+- 提取 `audio` 字段并转为 URL（`base64_to_url()`）；
+- 设置播放器源并更新文本显示；
+- 播放完毕后等待 `'ended'` 事件再次调用自身。
+
+当数据耗尽时清空界面。
+
+---
+
+## 5. 工厂注册
+
+所有组件均通过 `bricks.Factory` 注册，可在模板中使用标签方式实例化。
+
+```js
+bricks.Factory.register('AudioPlayer', bricks.AudioPlayer);
+bricks.Factory.register('AudioRecorder', bricks.AudioRecorder);
+bricks.Factory.register('TextedAudioPlayer', bricks.TextedAudioPlayer);
+```
+
+### 示例用法（假设支持声明式语法）
+
+```html
+<widget type="AudioPlayer" url="demo.mp3" autoplay="true"/>
+<widget type="AudioRecorder" upload_url="/api/upload-audio"/>
+<widget type="TextedAudioPlayer"/>
+```
+
+---
+
+## 6. 辅助函数与约定
+
+### `base64_to_url(base64str) → string`
+
+将 Base64 编码的音频数据转换为 `ObjectURL`，供 `<audio>` 使用。
+
+> ✅ 实际代码中需确保此函数存在。
+
+---
+
+### `schedule_once(fn, delay)`
+
+延迟执行一次函数（通常为 `setTimeout(fn, delay * 1000)` 封装）。
+
+---
+
+### `bricks.debug(msg, ...args)`
+
+框架级调试日志输出。
+
+---
+
+### `bricks.is_mobile() → boolean`
+
+判断是否运行在移动设备上，影响下载行为处理。
+
+---
+
+## 7. 使用场景建议
+
+| 场景 | 推荐组件 |
+|------|----------|
+| 普通音频播放 | `AudioPlayer` |
+| 用户录音上传 | `AudioRecorder` |
+| AI语音对话（TTS+字幕） | `TextedAudioPlayer` + 流式 API |
+| 连续播放多个短音频 | `AudioPlayer.set_stream_urls()` |
+
+---
+
+## 8. 注意事项
+
+1. **跨域限制**：录音上传、音频源加载需注意 CORS。
+2. **HTTPS 要求**：现代浏览器要求 `getUserMedia()` 在安全上下文中运行（HTTPS 或 localhost）。
+3. **移动端兼容性**：iOS Safari 对自动播放和 `ObjectURL` 支持有限，建议用户交互后触发播放。
+4. **内存管理**：使用 `URL.revokeObjectURL()` 及时释放资源。
+5. **错误处理**：建议监听 `error` 事件并在 UI 中反馈。
+
+---
+
+## 9. 示例代码
+
+### 初始化一个播放器
+
+```js
+const player = new bricks.AudioPlayer({
+    url: 'music.mp3',
+    autoplay: true
+});
+document.body.appendChild(player.dom_element);
+```
+
+### 创建录音器并绑定上传
+
+```js
+const recorder = new bricks.AudioRecorder({
+    upload_url: '/api/v1/audio-upload',
+    icon_rate: 1.2
+});
+recorder.bind('uploaded', (res) => {
+    console.log('Upload success:', res);
+});
+document.body.appendChild(recorder.dom_element);
+```
+
+### 流式语音播放（AI 回复）
+
+```js
+fetch('/api/stream-tts', { method: 'POST', body: prompt })
+.then(response => {
+    const tap = new bricks.TextedAudioPlayer();
+    tap.set_stream_urls(response);
+    document.body.appendChild(tap.dom_element);
+});
+```
+
+---
+
+> 📚 文档版本：v1.0  
+> © 2025 bricks Framework Team
\ No newline at end of file
diff --git a/aidocs/bar.md b/aidocs/bar.md
new file mode 100644
index 0000000..6834997
--- /dev/null
+++ b/aidocs/bar.md
@@ -0,0 +1,211 @@
+# `bricks.ChartBar` 技术文档
+
+> 基于 ECharts 的柱状图组件，用于快速生成基于数据配置的柱状图表。
+
+---
+
+## 概述
+
+`bricks.ChartBar` 是 `bricks` 框架中的一个图表扩展类，继承自 `bricks.EchartsExt`。它封装了使用 [Apache ECharts](https://echarts.apache.org/) 绘制**柱状图（Bar Chart）**所需的基本逻辑，支持通过配置项动态加载数据并渲染图表。
+
+该组件适用于需要展示分类维度下多个指标对比的场景，例如销量统计、用户增长等。
+
+---
+
+## 类定义
+
+```javascript
+bricks.ChartBar = class extends bricks.EchartsExt
+```
+
+- **命名空间**: `bricks.ChartBar`
+- **父类**: `bricks.EchartsExt`
+- **注册名称**: `'ChartBar'`（通过 `bricks.Factory.register` 注册）
+
+---
+
+## 配置参数
+
+`ChartBar` 支持以下初始化配置项：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `data_url` | `String` (可选) | 数据请求的 URL 地址。若提供，则通过 AJAX 获取数据。 |
+| `data_params` | `Object` (可选) | 发送请求时携带的参数（与 `data_url` 配合使用）。 |
+| `method` | `String` (可选) | 请求方法，默认为 `'GET'`，可设为 `'POST'` 等。 |
+| `data` | `Array<Object>` (可选) | 直接传入的数据数组，格式为对象列表。优先级高于 `data_url`。 |
+| `nameField` | `String` | 指定作为 X 轴分类字段的键名（如：地区、时间等）。 |
+| `valueFields` | `Array<String>` | 指定作为系列（Series）值字段的键名数组（即多个指标列）。 |
+
+### 示例数据结构
+
+```json
+[
+  { "category": "A", "sales": 120, "profit": 80 },
+  { "category": "B", "sales": 150, "profit": 90 }
+]
+```
+
+对应配置：
+```js
+{
+  data: [...],
+  nameField: "category",
+  valueFields: ["sales", "profit"]
+}
+```
+
+---
+
+## 方法说明
+
+### `values_from_data(data, name)`
+
+从数据集中提取指定字段的所有值。
+
+#### 参数
+- `data`: `Array<Object>` - 数据源数组。
+- `name`: `String` - 要提取的字段名。
+
+#### 返回值
+- `Array` - 包含所有 `data[i][name]` 值的数组。
+
+#### 示例
+```js
+this.values_from_data([
+  { year: '2020', sales: 100 },
+  { year: '2021', sales: 130 }
+], 'sales');
+// → [100, 130]
+```
+
+---
+
+### `lineinfo_from_data(data, name)`
+
+构建单个 ECharts Series 配置对象（类型为 bar）。
+
+#### 参数
+- `data`: `Array<Object>` - 数据源。
+- `name`: `String` - 字段名，用作 series 名称和数据提取依据。
+
+#### 返回值
+```js
+{
+  name: String,
+  type: 'bar',
+  data: Array // 提取自 data 中该字段的值
+}
+```
+
+#### 示例
+```js
+this.lineinfo_from_data(data, 'sales');
+// → { name: 'sales', type: 'bar', data: [100, 130] }
+```
+
+---
+
+### `setup_options(data)`
+
+根据输入数据生成完整的 ECharts 配置选项（`option` 对象）。
+
+#### 参数
+- `data`: `Array<Object>` - 处理后的数据集。
+
+#### 返回值 (`Object`)
+返回标准的 ECharts 配置对象，包含：
+
+```js
+{
+  tooltip: { trigger: 'axis' },
+  legend: { data: [...] },         // 分类名称列表
+  xAxis: {
+    type: 'category',
+    data: [...]                    // nameField 对应的值列表
+  },
+  yAxis: {
+    type: 'value'
+  },
+  series: [ ... ]                  // 每个 valueField 对应一个 bar series
+}
+```
+
+#### 内部逻辑
+1. 提取 `nameField` 的值作为 X 轴和图例数据；
+2. 遍历 `valueFields`，为每个字段创建一个柱状图系列；
+3. 整合成最终的 `options` 对象供 ECharts 渲染使用。
+
+---
+
+## 使用示例
+
+```js
+var chart = new bricks.ChartBar({
+  data_url: '/api/sales-data',
+  nameField: 'month',
+  valueFields: ['income', 'expense']
+});
+
+chart.renderTo('#chart-container');
+```
+
+或直接传入数据：
+
+```js
+var chart = new bricks.ChartBar({
+  data: [
+    { month: 'Jan', income: 5000, expense: 3000 },
+    { month: 'Feb', income: 6000, expense: 3500 }
+  ],
+  nameField: 'month',
+  valueFields: ['income', 'expense']
+});
+
+chart.renderTo(document.getElementById('main'));
+```
+
+---
+
+## 图表渲染效果
+
+- **X 轴**：显示 `nameField` 的值（类别轴）。
+- **Y 轴**：数值轴，自动适配最大最小值。
+- **Tooltip**：开启轴触发提示，鼠标悬停显示各系列数值。
+- **Legend**：图例显示所有 `valueFields` 名称。
+- **Series**：每个 `valueField` 显示为一组柱子（支持多组并列柱状图）。
+
+---
+
+## 注册机制
+
+```js
+bricks.Factory.register('ChartBar', bricks.ChartBar);
+```
+
+允许通过工厂模式创建实例：
+
+```js
+bricks.Factory.create('ChartBar', config);
+```
+
+---
+
+## 注意事项
+
+1. 必须确保页面已引入 ECharts 库且 `bricks.EchartsExt` 已正确定义。
+2. `nameField` 和 `valueFields` 必须存在于数据对象中。
+3. 若同时设置了 `data` 和 `data_url`，将优先使用 `data`。
+4. 支持异步数据加载，`data_url` 返回的数据应为 JSON 数组。
+
+---
+
+## 版本信息
+
+- **作者**: bricks framework team
+- **版本**: 1.0.0
+- **依赖**: `ECharts`, `bricks.EchartsExt`
+
+--- 
+
+📌 *文档生成时间：2025-04-05*
\ No newline at end of file
diff --git a/aidocs/binstreaming.md b/aidocs/binstreaming.md
new file mode 100644
index 0000000..d54e2be
--- /dev/null
+++ b/aidocs/binstreaming.md
@@ -0,0 +1,276 @@
+# Bricks 流媒体传输模块技术文档
+
+---
+
+## 概述
+
+`bricks.UpStreaming` 和 `bricks.down_streaming` 是用于实现浏览器端流式数据上传与下载的 JavaScript 工具类，基于现代 Web API（如 `ReadableStream` 和 `fetch`）构建。该模块适用于需要实时上传二进制数据（如音频、视频流）或处理响应流的场景。
+
+主要功能包括：
+
+- **上行流（UpStreaming）**：通过 `POST` 请求将数据以 `application/octet-stream` 格式分块发送至指定 URL。
+- **下行流解析器（down_streaming）**：异步生成器函数，用于消费 `Response.body` 的流式内容，并将其转换为字符串输出。
+
+---
+
+## 依赖说明
+
+本模块依赖以下现代浏览器特性：
+
+- `ReadableStream`
+- `Headers`
+- `fetch()` API（支持 `duplex: 'full'`）
+- `async/await` 与 `async generator` 函数
+- `TextDecoder`（隐含在 `String.fromCharCode` 使用中）
+
+> ⚠️ 注意：`duplex: 'full'` 是处理流式请求所必需的，目前仅在部分现代浏览器（如 Chrome 105+）中支持。
+
+---
+
+## 命名空间初始化
+
+```js
+bricks = window.bricks || {};
+```
+
+确保 `bricks` 全局命名空间存在，避免覆盖已有定义。
+
+---
+
+## 类：`bricks.UpStreaming`
+
+继承自 `bricks.JsWidget`，提供流式上传能力。
+
+### 继承关系
+
+```js
+class UpStreaming extends bricks.JsWidget
+```
+
+> 需确保 `bricks.JsWidget` 已正确定义并可用。
+
+---
+
+### 构造函数
+
+```js
+constructor(opts)
+```
+
+#### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `opts` | Object | 配置对象，必须包含 `url` 字段 |
+
+示例配置：
+```js
+{
+  url: "https://example.com/upload"
+}
+```
+
+#### 实现逻辑
+
+调用父类构造函数 `super(opts)`，初始化组件基础属性。
+
+---
+
+### 方法
+
+#### `async go()`
+
+启动流式上传请求。
+
+##### 返回值
+
+- `{Promise<Response>}`：返回一个 resolve 为 `Response` 对象的 Promise。
+
+##### 实现细节
+
+1. 创建一个可读流 `this.body`，使用当前实例作为其源（source）。
+2. 设置请求头：
+   - `Content-Type: application/octet-stream`
+3. 使用 `fetch` 发起 POST 请求：
+   ```js
+   fetch(this.url, {
+     method: 'POST',
+     headers: this.headers,
+     duplex: 'full',
+     body: this.body
+   })
+   ```
+4. 返回响应 `Response` 对象。
+
+> 💡 `duplex: 'full'` 表示客户端可以同时写入请求体并读取响应，常用于流式接口。
+
+---
+
+#### `send(data)`
+
+向流中写入一段数据。
+
+##### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `data` | ArrayBuffer / Uint8Array 等 | 要发送的二进制数据块 |
+
+##### 实现
+
+调用内部控制器的 `enqueue` 方法将数据推入流队列：
+
+```js
+this.stream_ctlr.enqueue(data);
+```
+
+> 必须在调用 `start()` 后才能使用此方法。
+
+---
+
+#### `finish()`
+
+关闭写入流，表示所有数据已发送完毕。
+
+##### 实现
+
+```js
+this.stream_ctlr.close();
+```
+
+通知流结束，触发底层请求完成。
+
+---
+
+#### `start(controller)`
+
+流控制器初始化钩子（由 `ReadableStream` 调用）。
+
+##### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `controller` | ReadableStreamController | 浏览器提供的流控制对象 |
+
+##### 实现
+
+保存控制器引用以便后续调用：
+
+```js
+this.stream_ctlr = controller;
+```
+
+> 此方法是 `ReadableStream` 构造时自动调用的标准接口。
+
+---
+
+## 函数：`bricks.down_streaming`
+
+异步生成器函数，用于逐段读取响应流并解码为字符串。
+
+```js
+bricks.down_streaming = async function*(response)
+```
+
+### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `response` | Response | 来自 `fetch` 的响应对象 |
+
+### 返回值
+
+- `{AsyncGenerator<string>}`：异步生成器，每次 `yield` 一个字符串片段。
+
+### 实现逻辑
+
+1. 若 `response` 为空，则直接返回。
+2. 获取响应体的读取器：`response.body.getReader()`
+3. 循环调用 `reader.read()` 直到流结束（`done === true`）。
+4. 将每一块 `Uint8Array` 数据转换为字符串：
+   ```js
+   String.fromCharCode(...value.value)
+   ```
+   > ❌ 注意：这种方式对非 ASCII 字符（如中文）可能出错，推荐使用 `TextDecoder`。
+5. 输出日志并 `yield` 结果。
+
+### 示例用法
+
+```js
+for await (const chunk of bricks.down_streaming(resp)) {
+  console.log('Received:', chunk);
+}
+```
+
+---
+
+## 使用示例
+
+### 上行流发送数据
+
+```js
+const uploader = new bricks.UpStreaming({
+  url: '/api/stream-upload'
+});
+
+// 启动上传
+const respPromise = uploader.go();
+
+// 发送若干数据块
+uploader.send(new TextEncoder().encode("Hello"));
+uploader.send(new TextEncoder().encode("World"));
+
+// 完成上传
+uploader.finish();
+
+// 获取响应
+const resp = await respPromise;
+console.log('Upload complete:', resp.status);
+```
+
+### 下行流接收数据
+
+```js
+const response = await fetch('/api/stream-download');
+for await (const textChunk of bricks.down_streaming(response)) {
+  console.log('Chunk:', textChunk);
+}
+```
+
+---
+
+## 注意事项与优化建议
+
+1. ✅ **兼容性警告**  
+   `duplex: 'full'` 并非所有浏览器都支持，请在使用前检测环境支持情况。
+
+2. ⚠️ **字符编码问题**  
+   当前行内使用 `String.fromCharCode` 解码字节数组，**不支持 UTF-8 多字节字符**。  
+   建议改进为使用 `TextDecoder`：
+
+   ```js
+   const decoder = new TextDecoder('utf-8');
+   let result = decoder.decode(value.value);
+   ```
+
+3. 🔒 **错误处理缺失**  
+   当前代码未捕获 `fetch` 或 `reader.read()` 中可能出现的异常，建议添加 `try-catch`。
+
+4. 📦 **内存管理**  
+   大量频繁调用 `send()` 可能导致内存堆积，建议结合背压机制（backpressure）进行流控。
+
+---
+
+## 总结
+
+| 功能 | 类/函数 | 用途 |
+|------|--------|------|
+| 流式上传 | `bricks.UpStreaming` | 实现双向流上传数据 |
+| 流式下载解析 | `bricks.down_streaming` | 异步解析响应流为字符串 |
+
+该模块适用于实时音视频通信、大文件分片上传、AI 流式推理等场景，具备良好的扩展潜力。
+
+--- 
+
+> 文档版本：v1.0  
+> 最后更新：2025-04-05
\ No newline at end of file
diff --git a/aidocs/bricks.md b/aidocs/bricks.md
new file mode 100644
index 0000000..1d10a57
--- /dev/null
+++ b/aidocs/bricks.md
@@ -0,0 +1,498 @@
+# Bricks.js 技术文档
+
+> **Bricks.js** 是一个基于 JavaScript 的前端组件化框架，用于构建可扩展、模块化的 Web 应用程序。它支持动态组件加载、事件绑定、数据实时获取、弹窗管理、国际化（i18n）、媒体流控制等功能。
+
+---
+
+## 目录
+
+- [1. 概述](#1-概述)
+- [2. 核心对象 `bricks`](#2-核心对象-bricks)
+- [3. 绑定动作（Bind Actions）](#3-绑定动作bind-actions)
+  - [通用属性](#通用属性)
+  - [各类型绑定的特定属性](#各类型绑定的特定属性)
+- [4. 工具函数](#4-工具函数)
+  - [`uuid()`](#uuid)
+  - [`deviceid(appname)`](#deviceidappname)
+  - [`str2data(s, d)`](#str2datas-d)
+  - [`apply_data(desc, data)`](#apply_datadesc-data)
+- [5. 组件构建系统](#5-组件构建系统)
+  - [`widgetBuild(desc, widget, data)`](#widgetbuilddesc-widget-data)
+  - [`buildBind(w, desc)`](#buildbindw-desc)
+  - [`buildEventBind(from_widget, widget, event, desc)`](#buildeventbindfrom_widget-widget-event-desc)
+  - [`universal_handler(from_widget, widget, desc, event)`](#universal_handlerfrom_widget-widget-desc-event)
+- [6. 事件处理器生成器](#6-事件处理器生成器)
+  - [`buildEventHandler(w, desc, event)`](#buildeventhandlerw-desc-event)
+  - [`getRealtimeData(w, desc)`](#getrealtimedataw-desc)
+- [7. 各类 Handler 构造函数](#7-各类-handler-构造函数)
+  - [`buildNewWindowHandler`](#buildnewwindowhandler)
+  - [`buildUrlwidgetHandler`](#buildurlwidgethandler)
+  - [`buildBricksHandler`](#buildbrickshandler)
+  - [`buildRegisterFunctionHandler`](#buildregisterfunctionhandler)
+  - [`buildMethodHandler`](#buildmethodhandler)
+  - [`buildScriptHandler`](#buildscripthandler)
+  - [`buildDispatchEventHandler`](#builddispatcheventhandler)
+- [8. 辅助函数](#8-辅助函数)
+  - [`getWidgetById(id, from_widget)`](#getwidgetbyidid-from_widget)
+- [9. App 类 (`bricks.App`)](#9-app-类-bricksapp)
+  - [构造函数参数 `opts`](#构造函数参数-opts)
+  - [主要方法](#主要方法)
+
+---
+
+## 1. 概述
+
+`bricks` 是一个全局命名空间对象，封装了整个应用的核心逻辑：
+
+```js
+var bricks = window.bricks || {};
+bricks.app = null;
+```
+
+所有功能均挂载在 `bricks` 对象下，包括：
+- 组件工厂（Factory）
+- 弹窗管理（Popup / PopupWindow）
+- HTTP 请求客户端（HttpJson）
+- 国际化支持（I18n）
+- 设备标识与会话管理
+- 动态组件构建与事件绑定机制
+
+---
+
+## 2. 核心对象 `bricks`
+
+| 属性/方法         | 类型       | 描述 |
+|------------------|-----------|------|
+| `app`            | App 实例  | 当前应用主实例 |
+| `Body`           | DOM 元素包装 | 页面 body 封装 |
+| `bug` / `debug`  | Boolean   | 是否开启调试模式 |
+| `Factory`        | Class     | 组件注册与创建工厂 |
+| `RF`             | RegisterFunction | 注册函数管理器 |
+
+---
+
+## 3. 绑定动作（Bind Actions）
+
+通过 `desc.binds` 数组定义用户交互行为，每个绑定描述符包含以下结构。
+
+### 通用属性
+
+所有绑定动作都具备以下字段：
+
+| 字段名           | 类型     | 必填 | 描述 |
+|------------------|----------|------|------|
+| `actiontype`     | String   | ✅   | 动作类型：`bricks`, `urlwidget`, `method`, `script`, `registerfunction`, `event`, `newwindow` |
+| `wid`            | String   | ✅   | 触发事件的组件 ID |
+| `event`          | String   | ✅   | 监听的事件名称，如 `'click'` |
+| `target`         | String 或 Widget | ✅ | 执行目标组件或特殊值（如 `'Popup'`） |
+| `datawidget`     | String   | ❌   | 获取运行时数据的源组件 ID |
+| `datamethod`     | String   | ❌   | 数据获取方法，默认 `'getValue'` |
+| `dataparams`     | Object   | ❌   | 调用 `datamethod` 的参数 |
+| `datascript`     | String   | ❌   | 自定义脚本获取数据 |
+| `rtdata`         | Object   | ❌   | 静态运行时数据 |
+| `conform`        | Object   | ❌   | 确认对话框配置，在执行前弹出确认窗口 |
+
+---
+
+### 各类型绑定的特定属性
+
+#### `urlwidget` action
+
+从远程 URL 加载组件描述并渲染。
+
+| 属性    | 类型     | 描述 |
+|--------|---------|------|
+| `mode` | String  | `'replace'`, `'insert'`, `'append'`，默认 `'replace'` |
+| `options.method` | String | HTTP 方法，默认 `'GET'` |
+| `options.params` | Object | 请求参数 |
+| `options.url`    | String | 远程组件 JSON 地址 |
+
+#### `bricks` action
+
+本地创建 Bricks 组件。
+
+| 属性    | 类型     | 描述 |
+|--------|---------|------|
+| `mode` | String  | 同上 |
+| `options.widgettype` | String | 组件类型，必须已注册 |
+| `options.*` | Any | 组件初始化选项 |
+
+#### `method` action
+
+调用目标组件的方法。
+
+| 属性     | 类型     | 描述 |
+|---------|----------|------|
+| `method` | String   | 方法名 |
+| `params` | Object   | 方法参数（kwargs） |
+
+#### `script` action
+
+执行内联脚本。
+
+| 属性     | 类型     | 描述 |
+|---------|----------|------|
+| `script` | String   | 可执行 JS 代码字符串（异步函数体） |
+| `params` | Object   | 传入脚本的参数 |
+
+#### `registerfunction` action
+
+调用已注册的全局函数。
+
+| 属性      | 类型     | 描述 |
+|----------|----------|------|
+| `rfname` | String   | 注册函数名称 |
+| `params` | Object   | 函数参数 |
+
+#### `event` action
+
+派发自定义事件。
+
+| 属性             | 类型     | 描述 |
+|------------------|----------|------|
+| `dispatch_event` | String   | 要派发的事件名 |
+| `params`         | Object   | 携带的数据 |
+
+---
+
+## 4. 工具函数
+
+### `uuid()`
+
+生成唯一标识符（UUID），优先使用 Web Crypto API，降级为随机字符串。
+
+```js
+bricks.uuid(); // 返回类似 "a1b2c3d4e5f6..."
+```
+
+- 使用 `crypto.randomUUID()`（现代浏览器）
+- 若不支持，则生成 30 位随机字符（来自字母数字集）
+
+> ⚠️ 注意：降级版本非标准 UUID，仅作唯一性参考。
+
+---
+
+### `deviceid(appname)`
+
+为当前设备+应用组合生成持久化设备 ID，存储于 `localStorage`。
+
+```js
+bricks.deviceid('myapp'); // → myappdeviceid: abcdef...
+```
+
+- Key: `${appname}deviceid`
+- 自动生成并缓存，避免重复访问时变化
+
+---
+
+### `str2data(s, d)`
+
+模板字符串解析函数，支持变量插值和类型转换。
+
+**语法格式：**
+
+```
+'my name is ${name}, age ${age:type}'
+```
+
+支持的类型：
+- `int`: 转为整数
+- `str`: 字符串（默认）
+- `json`: JSON 序列化
+
+**示例：**
+
+```js
+bricks.str2data('Hello ${user}', { user: 'Tom' }); 
+// → "Hello Tom"
+
+bricks.str2data('${data:json}', { data: { x: 1 } });
+// → '{"x":1}'
+```
+
+返回 `null` 如果关键变量缺失。
+
+---
+
+### `apply_data(desc, data)`
+
+将数据填充到任意对象结构中（递归模板替换）。
+
+```js
+const desc = { url: '/api/${id}' };
+const filled = bricks.apply_data(desc, { id: 123 });
+// → { url: '/api/123' }
+```
+
+内部使用 `str2data` 处理所有字符串字段。
+
+---
+
+## 5. 组件构建系统
+
+### `widgetBuild(desc, widget, data)`
+
+根据组件描述符异步构建组件树。
+
+**参数：**
+- `desc`: 组件描述对象（含 `widgettype`, `options`, `subwidgets`, `binds`）
+- `widget`: 父组件（上下文）
+- `data`: 初始数据，用于模板填充
+
+**流程：**
+1. 若 `widgettype === 'urlwidget'`，先发起 HTTP 请求获取真实组件描述
+2. 应用 `data` 填充模板
+3. 查找组件类（通过 `Factory.get(type)`）
+4. 创建实例并设置 `id`
+5. 递归构建子组件（`subwidgets`）
+6. 绑定事件（`binds`）
+
+**返回：** 构建完成的组件实例（Promise）
+
+---
+
+### `buildBind(w, desc)`
+
+为指定组件建立事件绑定。
+
+**步骤：**
+1. 解析 `wid` 得到触发源组件
+2. 调用 `buildEventBind(...)` 添加监听器
+
+---
+
+### `buildEventBind(from_widget, widget, event, desc)`
+
+实际绑定事件处理器。
+
+```js
+widget.bind(event, handler);
+```
+
+处理器为 `bricks.universal_handler(from_widget, widget, desc)` 的柯里化函数。
+
+---
+
+### `universal_handler(from_widget, widget, desc, event)`
+
+统一事件处理入口，支持前置确认（`conform`）。
+
+**逻辑：**
+- 若有 `conform` 配置，创建 `Conform` 弹窗，确认后再执行后续操作
+- 否则直接调用 `buildEventHandler(...)`
+
+若失败，输出调试信息。
+
+---
+
+## 6. 事件处理器生成器
+
+### `buildEventHandler(w, desc, event)`
+
+根据 `actiontype` 分发不同类型的处理器。
+
+| actiontype         | 返回处理器函数 |
+|--------------------|----------------|
+| `newwindow`        | 新窗口打开链接 |
+| `urlwidget`        | 加载远程组件 |
+| `bricks`           | 创建本地组件 |
+| `registerfunction` | 调用注册函数 |
+| `method`           | 调用组件方法 |
+| `script`           | 执行脚本 |
+| `event`            | 派发事件 |
+
+同时处理：
+- 实时数据提取（`rtdata` 来源：`datawidget`, `datamethod`, `datascript`）
+- 参数映射（`params_mapping`）
+- 事件参数合并
+
+---
+
+### `getRealtimeData(w, desc)`
+
+从指定组件获取实时数据。
+
+**方式：**
+- `desc.method`: 调用组件方法
+- `desc.script`: 执行脚本获取结果
+
+**返回：** Promise 包裹的结果数据
+
+---
+
+## 7. 各类 Handler 构造函数
+
+这些函数返回一个“延迟执行”的函数（通常用 `.bind()` 封装），供事件触发时调用。
+
+### `buildNewWindowHandler`
+
+打开新浏览器窗口。
+
+- 支持参数拼接（URL 查询参数）
+- 使用 `_buildWidget` 渲染 `NewWindow` 组件
+
+---
+
+### `buildUrlwidgetHandler`
+
+加载远程组件并在目标位置展示。
+
+- 支持 `FormData` 特殊处理（POST 提交）
+- 参数自动注入 URL 或请求体
+
+---
+
+### `buildBricksHandler`
+
+在目标容器中渲染本地 Bricks 组件。
+
+- 支持 `mode`: `replace`, `insert`, `append`
+- 自动处理弹窗打开（Popup/PopupWindow）
+
+---
+
+### `buildRegisterFunctionHandler`
+
+调用通过 `bricks.RF.register(name, func)` 注册的函数。
+
+- 参数合并策略：`desc.params` + `rtdata` + `event_params`
+- 支持模板填充
+
+---
+
+### `buildMethodHandler`
+
+调用目标组件上的某个方法。
+
+```js
+target[desc.method].bind(target, params)
+```
+
+适用于 `setValue`, `show`, `hide` 等组件 API。
+
+---
+
+### `buildScriptHandler`
+
+动态创建异步函数并绑定执行环境。
+
+```js
+const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+new AsyncFunction('params', 'event', scriptBody);
+```
+
+可用于复杂逻辑脚本注入。
+
+---
+
+### `buildDispatchEventHandler`
+
+向目标组件派发自定义事件。
+
+```js
+target.dispatch(desc.dispatch_event, mergedParams);
+```
+
+常用于跨组件通信。
+
+---
+
+## 8. 辅助函数
+
+### `getWidgetById(id, from_widget)`
+
+根据 ID 查找组件实例，支持路径表达式。
+
+**ID 支持语法：**
+- `'self'`: 当前组件
+- `'root'`: 根组件
+- `'app'` / `'body'`: 应用主体
+- `'window'`: 浏览器窗口根元素
+- `'#id'`: DOM ID 选择器
+- `'-id'`: 使用 `closest()` 向上查找
+
+**示例：**
+```js
+bricks.getWidgetById('loginForm.usernameInput');
+```
+
+返回匹配的 `bricks_widget` 实例或原生 DOM。
+
+---
+
+## 9. App 类 (`bricks.App`)
+
+继承自 `bricks.Layout`，是整个应用的根容器。
+
+### 构造函数参数 `opts`
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `appname` | String | 应用名，用于设备 ID 存储 |
+| `debug` | Boolean/String | 是否启用调试日志 |
+| `login_url` | String | 登录页地址，默认 `/rbac/userpassword_login.ui` |
+| `charsize` | Number | 字体基础大小 |
+| `language` | String | 初始语言（如 `'zh-CN'`） |
+| `i18n.url` | String | 国际化资源接口 |
+| `i18n.default_lang` | String | 默认语言 |
+| `widget` | Object | 根组件描述 |
+
+### 主要方法
+
+| 方法 | 描述 |
+|------|------|
+| `run()` | 启动应用：初始化语言、构建根组件、添加至 DOM |
+| `build()` | 构建根组件树 |
+| `change_language(lang)` | 切换语言并通知 i18n 系统 |
+| `key_down_action(event)` | 全局键盘事件捕获 |
+| `new_zindex()` | 获取新的 z-index 层级 |
+| `screenWidth()` / `screenHeight()` | 获取视口尺寸 |
+| `save_session(session)` / `get_session()` | 会话管理 |
+| `start_camera(vpos)` | 打开指定摄像头 |
+| `start_mic()` | 打开麦克风 |
+| `getCameras()` | 获取可用视频输入设备列表 |
+| `textsize_bigger()` / `textsize_smaller()` | 调整字体大小 |
+| `show_windows_panel()` | 显示多窗口面板（实验性） |
+
+---
+
+## 附录 A：内置组件类型（常见 `widgettype`）
+
+| 类型 | 说明 |
+|------|------|
+| `Text` | 文本显示 |
+| `Button` | 按钮 |
+| `Input` | 输入框 |
+| `Layout` | 布局容器 |
+| `Popup` | 模态弹窗 |
+| `PopupWindow` | 独立窗口弹窗 |
+| `Conform` | 确认对话框 |
+| `NewWindow` | 新浏览器窗口包装器 |
+| `WindowsPanel` | 窗口管理面板 |
+
+---
+
+## 附录 B：调试技巧
+
+启用调试：
+```js
+bricks.bug = true;
+```
+
+查看日志：
+```js
+console.log(...args); // 内部使用 debug 输出
+```
+
+推荐配合 Chrome DevTools 使用。
+
+---
+
+## 许可证
+
+MIT License（假设项目允许）
+
+--- 
+
+> 📝 文档版本：v1.0  
+> ✍️ 最后更新：2025年4月5日
\ No newline at end of file
diff --git a/aidocs/button.md b/aidocs/button.md
new file mode 100644
index 0000000..cf60c23
--- /dev/null
+++ b/aidocs/button.md
@@ -0,0 +1,254 @@
+# `bricks.Button` 技术文档
+
+> 继承自：`bricks.Layout`
+
+`bricks.Button` 是一个可交互的按钮组件，支持图标、文本标签、自定义样式以及点击事件处理。它基于 Flexbox 布局进行内容排列，适用于水平或垂直方向的内容展示。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [配置选项（Options）](#配置选项options)
+- [结构与布局](#结构与布局)
+- [方法说明](#方法说明)
+  - [`constructor(opts)`](#constructoro)
+  - [`create()`](#create)
+  - [`opts_setup()`](#opts_setup)
+  - [`target_clicked(event)`](#target_clickedevent)
+- [事件机制](#事件机制)
+- [注册信息](#注册信息)
+
+---
+
+## 概述
+
+`bricks.Button` 提供了一个封装良好的按钮控件，可用于触发操作或导航。该组件可以包含：
+
+- 图标（通过 `bricks.Icon`）
+- 文本标签（通过 `bricks.Text`）
+- 自定义 CSS 样式
+- 工具提示（tooltip）
+- 可配置的布局方向（横向/纵向）
+
+所有子元素使用 Flexbox 排列，并可通过 `item_rate` 控制尺寸比例。
+
+---
+
+## 配置选项（Options）
+
+| 属性名         | 类型     | 描述 |
+|----------------|----------|------|
+| `orientation`  | String   | 布局方向，可选 `'horizontal'` 或默认为垂直 `'vertical'`。影响内部图标的排列方式。 |
+| `height`       | CSS value | 容器高度，默认 `100%`（由父级控制）。 |
+| `width`        | CSS value | 容器宽度，默认 `100%`。 |
+| `item_rate`    | Number   | 子元素（图标/文字）的缩放比率，默认为 `1`。用于调整大小。 |
+| `tooltip`      | String   | 鼠标悬停时显示的提示文本，设置到 DOM 的 `title` 属性上。 |
+| `color`        | String   | 文字颜色（传递给 `Text` 组件）。 |
+| `bgcolor`      | String   | 背景颜色（传递给 `Text` 组件）。 |
+| `nonepack`     | Boolean  | 是否移除内边距和边框；若为 `true`，则 padding 设为 `0px`，border 为 `0`。 |
+| `name`         | String   | 组件名称，用作 DOM 元素 ID 的基础。 |
+| `icon`         | String   | 图标资源 URL 或路径，用于创建 `bricks.Icon` 实例。 |
+| `label`        | String   | 显示的文字标签，支持国际化（i18n）。 |
+| `css`          | Object   | 自定义 CSS 样式对象，将被合并到 DOM 元素的 `style` 中。 |
+| `action`       | Object   | 点击按钮后执行的动作配置，详见下表。 |
+
+### `action` 对象结构
+
+| 子属性         | 类型     | 描述 |
+|----------------|----------|------|
+| `target`       | String   | 目标组件或模块名称。 |
+| `datawidget`   | String   | 数据源控件名。 |
+| `datamethod`   | String   | 数据获取方法名。 |
+| `datascript`   | String   | 自定义脚本逻辑（如函数体字符串）。 |
+| `dataparams`   | Object   | 发送至数据接口的参数。 |
+| `rtdata`       | Boolean  | 是否实时刷新数据。 |
+| `actiontype`   | String   | 动作类型，例如 `"navigate"`、`"submit"` 等。 |
+| `...`          | Any      | 其他扩展字段，根据业务需求定义。 |
+
+---
+
+## 结构与布局
+
+- 使用 `<button>` 元素作为根节点。
+- 内部采用 `display: flex` 进行布局：
+  - 水平布局：`flex-direction: row`
+  - 垂直布局：`flex-direction: column`
+- 支持图标在上、文字在下的垂直排布，或并排的水平排布。
+- 默认具有 `0.5rem` 的内边距，除非设置了 `nonepack: true`。
+
+```css
+{
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  text-align: center;
+  padding: 0.5rem; /* 或 0px（当 nonepack=true） */
+}
+```
+
+---
+
+## 方法说明
+
+### `constructor(opts)`
+
+初始化按钮实例，继承自 `Layout` 并设置基本样式和属性。
+
+#### 参数
+
+- `opts` (Object): 配置选项对象。
+
+#### 行为
+
+1. 调用父类构造函数 `super(opts)`。
+2. 初始化默认样式对象（Flex 布局相关）。
+3. 根据 `nonepack` 设置是否去除 padding 和 border。
+4. 根据 `orientation` 设置 `flexDirection` 并记录简写形式（`this.orient = 'h'|'v'`）。
+5. 设置组件 ID 为 `opts.name`。
+6. 执行 `opts_setup()` 创建子组件（图标/文本）。
+7. 合并默认样式与用户自定义样式到 `dom_element.style`。
+
+---
+
+### `create()`
+
+创建底层 DOM 元素。
+
+```js
+this.dom_element = document.createElement('button');
+```
+
+> 此方法在组件生命周期中自动调用，无需手动执行。
+
+---
+
+### `opts_setup()`
+
+根据配置项创建子控件（图标和/或文本），并将它们添加到当前容器中。
+
+#### 行为
+
+- 如果存在 `opts.icon`，创建一个 `bricks.Icon` 实例，并绑定点击事件。
+- 如果存在 `opts.label`，创建一个 `bricks.Text` 实例，启用 i18n 支持，并绑定点击事件。
+- 所有子控件均通过 `add_widget()` 加入布局。
+- 文本控件引用保存在 `this.text_w` 上，便于后续更新。
+
+#### 示例代码片段
+
+```js
+if (this.opts.icon) {
+  const icon = new bricks.Icon({
+    rate: this.item_rate,
+    url: this.opts.icon
+  });
+  this.add_widget(icon);
+  icon.bind('click', this.target_clicked.bind(this));
+}
+```
+
+---
+
+### `target_clicked(event)`
+
+处理按钮点击事件的核心方法。
+
+#### 参数
+
+- `event` (Event): 浏览器原生事件对象。
+
+#### 行为
+
+1. 输出调试日志：`bricks.debug('target_clicked() .... called ')`
+2. 阻止事件冒泡（`event.stopPropagation()`）
+3. 触发组件自身的 `'click'` 事件，并携带完整 `opts` 数据。
+4. 若配置了 `action`，且启用了 `debug` 模式，则输出完整的 `opts` 到控制台。
+
+#### 示例输出（debug 模式）
+
+```text
+debug:opts= { name: "btn_save", action: { target: "form", actiontype: "submit" }, ... }
+```
+
+---
+
+## 事件机制
+
+| 事件名   | 触发时机               | 携带数据           |
+|----------|------------------------|--------------------|
+| `click`  | 用户点击按钮时         | `this.opts` 对象   |
+
+可通过 `.bind('click', handler)` 监听此事件：
+
+```js
+button.bind('click', function(data) {
+  console.log('Button clicked:', data.action);
+});
+```
+
+---
+
+## 注册信息
+
+```js
+bricks.Factory.register('Button', bricks.Button);
+```
+
+使得可以通过工厂模式动态创建按钮：
+
+```js
+const btn = bricks.Factory.create('Button', {
+  name: 'my_button',
+  label: 'Submit',
+  icon: '/icons/save.svg',
+  action: {
+    actiontype: 'submit',
+    target: 'form1'
+  }
+});
+```
+
+---
+
+## 使用示例
+
+```js
+const myButton = new bricks.Button({
+  name: 'btn_ok',
+  label: 'OK',
+  icon: '/icons/check.png',
+  orientation: 'horizontal',
+  item_rate: 1.2,
+  color: '#fff',
+  bgcolor: '#007bff',
+  tooltip: 'Click to confirm',
+  action: {
+    actiontype: 'navigate',
+    target: 'page_home'
+  },
+  debug: true
+});
+
+document.body.appendChild(myButton.dom_element);
+```
+
+---
+
+## 注意事项
+
+- 推荐配合 `bricks.Icon` 和 `bricks.Text` 使用以保持 UI 一致性。
+- 若需完全自定义外观，请使用 `css` 属性覆盖样式。
+- `nonepack: true` 适合嵌入紧凑型 UI 区域。
+- 所有文本自动支持国际化（i18n），前提是 `bricks.app.i18n` 已正确配置。
+
+---
+
+## 版本信息
+
+- **框架**：Bricks.js
+- **组件路径**：`bricks.Button`
+- **最后更新**：根据代码注释推断为近期维护版本
+
+--- 
+
+✅ *文档完*
\ No newline at end of file
diff --git a/aidocs/camera.md b/aidocs/camera.md
new file mode 100644
index 0000000..3db2ab2
--- /dev/null
+++ b/aidocs/camera.md
@@ -0,0 +1,355 @@
+# `bricks.Camera` 技术文档
+
+> 一个基于 `bricks.Popup` 的摄像头操作组件，支持拍照和视频录制功能。
+
+---
+
+## 概述
+
+`bricks.Camera` 是 `bricks` UI 框架中的一个类，继承自 `bricks.Popup`，用于在网页中实现摄像头访问、实时预览、拍照以及视频录制功能。它通过调用浏览器的 `MediaDevices.getUserMedia()` 接口获取摄像头流，并结合 HTML5 `<video>` 和 `<canvas>` 实现图像捕获与处理。
+
+该组件支持两种模式：
+- **拍照模式（picture）**：单张照片拍摄。
+- **录像模式（recorder）**：支持开始/停止录制 WebM 格式的视频。
+
+同时提供切换摄像头设备、删除取消等交互按钮。
+
+---
+
+## 继承关系
+
+```
+bricks.Popup
+   ↓
+bricks.Camera
+```
+
+---
+
+## 构造函数
+
+```js
+new bricks.Camera(options)
+```
+
+### 参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|-------|------|------|--------|------|
+| `opts.fps` | Number | 否 | `60` | 视频预览帧率（每秒帧数），影响 `show_picture` 调用频率 |
+| `opts.type` | String | 是 | `'picture'` | 模式类型：<br>`'picture'`: 拍照模式<br>`'recorder'`: 录像模式 |
+| `opts.auto_dismiss` | Boolean | 否 | `false` | 是否在操作后自动关闭弹窗（内部强制设为 `false`） |
+
+> ⚠️ 注意：`auto_dismiss` 在构造函数中被强制设置为 `false`，以防止误关闭。
+
+---
+
+## 属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `this.recordedChunks` | Array | 存储媒体录制过程中产生的数据块（Blob） |
+| `this.mediaRecorder` | MediaRecorder \| null | 浏览器原生 `MediaRecorder` 实例，用于视频录制 |
+| `this.stream` | MediaStream \| null | 来自摄像头的媒体流对象 |
+| `this.video` | HTMLVideoElement | 用于播放摄像头视频流的 `<video>` 元素 |
+| `this.imgw` | bricks.Image | 显示当前画面预览的图像控件 |
+| `this.shot_btn` | bricks.Svg | 拍照或开始/停止录制的按钮图标 |
+| `this.cur_camera_id` | Number | 当前使用的摄像头设备索引（未实际使用，建议优化） |
+| `this.task_period` | Number | 帧刷新周期（单位：秒），由 `fps` 计算得出 |
+| `this.task` | TaskHandle | 使用 `schedule_once` 创建的定时任务句柄 |
+| `this.dataurl` | String | 最近一帧画面的 Data URL（base64 编码的 JPEG 图像） |
+| `this.record_status` | String | 录制状态：<br>`''`（初始）<br>`'standby'`（待机）<br>`'recording'`（正在录制） |
+
+---
+
+## 方法
+
+### `constructor(opts)`
+
+初始化摄像头组件，创建 UI 布局并绑定事件。
+
+#### 内部逻辑
+1. 设置默认帧率和禁用自动关闭。
+2. 调用父类 `super(opts)` 初始化弹窗。
+3. 初始化录制相关变量。
+4. 创建 UI 结构：
+   - 上方填充区域显示实时画面（`this.imgw`）
+   - 下方水平工具栏包含：
+     - 切换摄像头按钮
+     - 拍照 / 录制按钮
+     - 删除（关闭）按钮
+5. 绑定按钮点击事件：
+   - `shot_btn`：根据模式执行 `take_picture` 或 `switch_recording`
+   - `switch_btn`：切换摄像头
+   - `del_btn`：关闭弹窗
+6. 延迟 0.1 秒启动摄像头（`startCamera`）
+
+---
+
+### `async startCamera(vpos?)`
+
+启动摄像头并开始视频流预览。
+
+#### 参数
+- `vpos` (Number, 可选)：指定摄像头设备索引（前置/后置）
+
+#### 流程
+1. 调用全局应用对象 `bricks.app.start_camera(vpos)` 获取摄像头流。
+2. 将流赋值给 `this.stream` 并绑定到 `<video>` 元素。
+3. 开始播放视频。
+4. 启动周期性任务 `show_picture`，按设定帧率更新预览图。
+
+#### 示例
+```js
+await this.startCamera(0); // 使用第一个摄像头
+```
+
+> ✅ 依赖全局 `bricks.app` 提供 `video_devices` 和 `video_stream`。
+
+---
+
+### `show_picture()`
+
+将当前视频帧渲染到预览区（通过 Canvas 截图）。
+
+#### 步骤
+1. 创建临时 `<canvas>`，尺寸匹配视频分辨率。
+2. 使用 `drawImage` 将视频当前帧绘制到 canvas。
+3. 转换为 JPEG Data URL（质量 95%）。
+4. 更新 `this.imgw` 显示新图像。
+5. 调用 `schedule_once` 自身，维持帧率循环。
+
+#### 性能提示
+- 若 `this.task_period === 0`，则退出循环（如拍照后停止）。
+- 使用 `requestAnimationFrame` 类似的调度机制（`schedule_once`）。
+
+---
+
+### `async switch_camera(btn, event)`
+
+切换摄像头设备（例如前后摄像头）。
+
+#### 参数
+- `btn`：触发按钮（SVG 图标）
+- `event`：点击事件对象（未使用）
+
+#### 行为
+1. 检查是否有多个摄像头（`bricks.app.video_devices.length < 2`）。
+2. 若只有一个摄像头，则禁用按钮。
+3. 否则，递增 `vpos`（`bricks.app.vpos`），循环切换。
+4. 调用 `startCamera(vpos)` 重新初始化摄像头。
+
+> 🔄 支持循环切换：0 → 1 → ... → n-1 → 0
+
+---
+
+### `switch_recording()`
+
+控制录像的开始与停止。
+
+#### 行为
+| 当前状态 | 动作 |
+|---------|------|
+| `recording` | 停止录制，按钮变“开始”图标 |
+| `standby` 或空 | 开始录制，按钮变“停止”图标 |
+
+#### 触发方法
+- `videorecorder_start()`：开始录制
+- `videorecorder_stop()`：停止录制
+
+---
+
+### `videorecorder_start()`
+
+使用 `MediaRecorder API` 开始录制视频。
+
+#### 异常
+- 如果 `this.stream` 未初始化，抛出错误。
+
+#### 配置
+- 使用 `new MediaRecorder(stream)`
+- 数据格式：`video/webm`
+- 监听 `ondataavailable`：收集每个 chunk 到 `recordedChunks`
+- 监听 `onstop`：
+  - 合并所有 chunks 成一个 Blob
+  - 创建 File 对象：`recorded_video.webm`
+  - 创建 Object URL（仅供调试日志）
+  - 触发 `recorded` 事件，携带生成的 `File`
+
+#### 示例输出
+```js
+dispatch('recorded', file); // file.type === "video/webm"
+```
+
+---
+
+### `videorecorder_stop()`
+
+手动停止媒体录制。
+
+```js
+this.mediaRecorder.stop();
+```
+
+> 自动触发 `onstop` 回调，完成文件合成与事件派发。
+
+---
+
+### `take_picture(event)`
+
+执行拍照操作。
+
+#### 参数
+- `event`：点击事件，调用 `stopPropagation()` 防止冒泡
+
+#### 行为
+1. 取消当前预览任务（`task.cancel()`）。
+2. 停止帧更新（`task_period = 0`）。
+3. 派发 `shot` 事件，携带最近一帧的 Data URL。
+
+#### 示例响应
+```js
+camera.bind('shot', function(dataurl) {
+    const img = document.createElement('img');
+    img.src = dataurl;
+    document.body.appendChild(img);
+});
+```
+
+---
+
+## UI 结构
+
+```text
++----------------------------------+
+|               [Preview]          |
+|         (bricks.Image: imgw)     |
++----------------------------------+
+| [Switch]   [Action]     [Delete] |
+| (SVG)       (SVG)        (SVG)  |
++----------------------------------+
+```
+
+- 使用 `bricks.HBox` 水平布局底部按钮栏
+- 使用 `bricks.Filler` 占位扩展空间
+- 所有按钮均为 `bricks.Svg` 组件，加载 SVG 资源图标
+
+---
+
+## 事件
+
+| 事件名 | 触发时机 | 携带数据 |
+|-------|----------|---------|
+| `shot` | 用户拍照完成 | `dataurl`（JPEG base64 字符串） |
+| `recorded` | 视频录制结束 | `File` 对象（WebM 格式） |
+
+可通过 `bind()` 方法监听：
+
+```js
+const camera = new bricks.Camera({ type: 'picture' });
+camera.bind('shot', (dataurl) => {
+    console.log('Photo taken:', dataurl);
+});
+camera.open();
+```
+
+---
+
+## 图标资源（SVG）
+
+| 按钮 | 图标路径 | 提示文字 |
+|------|--------|--------|
+| 拍照 | `imgs/camera.svg` | Take a picture |
+| 开始录制 | `imgs/start_recording.svg` | Start or stop record video |
+| 停止录制 | `imgs/stop_recording.svg` | Recording... |
+| 切换摄像头 | `imgs/switch-camera.svg` | switch camera |
+| 删除/取消 | `imgs/delete.svg` | canel it（应为 cancel） |
+
+> 图标路径通过 `bricks_resource()` 解析，通常指向 `/resources/...`
+
+---
+
+## 依赖项
+
+| 依赖 | 说明 |
+|------|------|
+| `bricks.Popup` | 父类，提供弹窗基础功能 |
+| `bricks.Svg` | SVG 图标按钮 |
+| `bricks.Image` | 图像显示控件 |
+| `bricks.HBox`, `bricks.Filler` | 布局容器 |
+| `bricks.app` | 全局应用对象，需提供：<br>- `video_devices`: 摄像头设备列表<br>- `vpos`: 当前设备索引<br>- `start_camera(vpos)`: 启动摄像头方法<br>- `video_stream`: 摄像头媒体流 |
+| `schedule_once(fn, delay)` | 自定义异步调度函数（类似 `setTimeout`，但可能集成任务队列） |
+| `bricks_resource(path)` | 资源路径解析函数 |
+
+---
+
+## 注册
+
+```js
+bricks.Factory.register('Camera', bricks.Camera);
+```
+
+允许通过工厂方式创建实例：
+
+```js
+bricks.Factory.create('Camera', { type: 'recorder' });
+```
+
+---
+
+## 使用示例
+
+### 拍照模式
+```js
+const camera = new bricks.Camera({
+    type: 'picture',
+    fps: 30
+});
+camera.bind('shot', (dataurl) => {
+    document.getElementById('result').src = dataurl;
+});
+camera.open();
+```
+
+### 录像模式
+```js
+const recorder = new bricks.Camera({
+    type: 'recorder',
+    fps: 25
+});
+recorder.bind('recorded', (file) => {
+    const url = URL.createObjectURL(file);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = 'video.webm';
+    a.click();
+});
+recorder.open();
+```
+
+---
+
+## 注意事项 & 改进建议
+
+| 问题 | 建议 |
+|------|------|
+| `record_status == ''` 应为 `=` | 修复拼写错误，避免逻辑 bug |
+| `task.cancel()` 中 `task` 应为 `this.task` | 修复变量引用错误 |
+| `tip:'canel it'` 拼写错误 | 改为 `'cancel it'` |
+| `this.cur_camera_id` 未更新 | 在 `switch_camera` 中同步更新 |
+| 不支持分辨率配置 | 可扩展 `opts.constraints` 传入 `getUserMedia` |
+| WebM 兼容性有限 | 可检测支持 MIME 类型，降级为 MP4（若支持） |
+| 缺少错误处理 UI | 添加摄像头权限失败提示 |
+
+---
+
+## 版本信息
+
+- **作者**：未知（来自 `bricks` 框架）
+- **最后修改**：根据代码推断为现代浏览器环境开发
+- **兼容性**：需支持 `MediaDevices`, `MediaRecorder`, `Canvas` 的现代浏览器（Chrome/Firefox/Edge）
+
+---
+
+📌 **总结**：  
+`bricks.Camera` 是一个功能完整、结构清晰的前端摄像头操作组件，适用于需要拍照或短时间录像的应用场景，如头像上传、短视频录制等。配合 `bricks` 框架可快速集成至项目中。
\ No newline at end of file
diff --git a/aidocs/cols.md b/aidocs/cols.md
new file mode 100644
index 0000000..937f96c
--- /dev/null
+++ b/aidocs/cols.md
@@ -0,0 +1,323 @@
+# `bricks.Cols` 技术文档
+
+> **模块**：`bricks.Cols`  
+> **继承自**：`bricks.VBox`  
+> **用途**：用于展示分页数据的列式布局组件，支持滚动加载、点击事件、动态渲染记录等特性。
+
+---
+
+## 概述
+
+`bricks.Cols` 是一个基于 `VBox` 布局容器构建的数据展示控件，专为高效展示大量可分页数据而设计。它通过垂直滚动加载前后页内容（懒加载），并以列的形式排列每条记录，适用于移动端和桌面端的响应式布局。
+
+该组件常用于新闻列表、商品展示、用户卡片墙等场景。
+
+---
+
+## 继承结构
+
+```
+bricks.Widget
+ └── bricks.Container
+      └── bricks.Box
+           └── bricks.VBox
+                └── bricks.Cols
+```
+
+---
+
+## 配置选项（Constructor Options）
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `data_url` | `String` | 获取数据的 API 地址，用于异步加载分页数据。 |
+| `data_params` | `Object` | 初始请求参数对象，在每次请求时合并发送。 |
+| `data_method` | `String` | 请求方法（如 `"GET"` 或 `"POST"`），默认由 `PageDataLoader` 决定。 |
+| `page_rows` | `Number` | 每页显示的数据行数。 |
+| `cache_limit` | `Number` | 缓存的最大页数，超出后自动清理旧页。 |
+| `col_width` | `String/Number` | 单个列的宽度（CSS 格式，如 `"200px"`）。 |
+| `col_cwidth` | `String` | 列的弹性宽度（CSS `flex` 值，如 `"1fr"`）。 |
+| `mobile_cols` | `Number` | 移动端每行显示的列数，默认为 `2`。 |
+| `record_view` | `Object` | 记录项的视图配置，定义如何使用 `widgetBuild` 渲染单条数据。 |
+| `title` | `String` | 可选标题文本（支持国际化）。 |
+| `description` | `String` | 可选描述文本（支持 Markdown）。 |
+| `toolbar` | `Object` | 工具栏配置对象，将被构造成 `bricks.Toolbar` 实例。 |
+
+---
+
+## 事件（Events）
+
+| 事件名 | 触发条件 | 参数 |
+|--------|----------|------|
+| `record_click` | 用户点击某条记录时触发 | `(recordData)` — 当前记录的原始数据对象 |
+| `command` | 工具栏发出命令时转发此事件（通过 `dispatch`） | 命令名称及参数 |
+
+> 使用 `.bind(event, handler)` 方法监听这些事件。
+
+---
+
+## 属性（Properties）
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `loader` | `bricks.PageDataLoader` | 分页数据加载器实例，负责管理前后页数据获取与缓存。 |
+| `container` | `bricks.VScrollPanel` | 外层垂直滚动容器，监听滚动阈值以触发分页加载。 |
+| `main` | `bricks.DynamicColumn` | 实际存放记录项的动态列容器。 |
+| `select_record` | `Widget` | 当前选中的记录对应的 widget 实例。 |
+| `loading` | `Boolean` | 是否正在加载数据，防止重复请求。 |
+| `title_w` | `bricks.Title4` | 标题组件实例（如果设置了 `title`）。 |
+| `desc_w` | `bricks.MdWidget` | 描述组件实例（如果设置了 `description`）。 |
+| `toolbar_w` | `bricks.Toolbar` | 工具栏组件实例（如果设置了 `toolbar`）。 |
+
+---
+
+## 方法（Methods）
+
+### `constructor(opts)`
+
+初始化 `Cols` 组件，并创建子组件结构。
+
+#### 流程说明：
+1. 调用父类构造函数。
+2. 初始化 `PageDataLoader` 加载器。
+3. 创建滚动容器 `VScrollPanel` 并绑定滚动边界事件。
+4. 根据配置添加标题、描述、工具栏。
+5. 创建主内容区域 `DynamicColumn`。
+6. 延迟 0.5 秒调用 `load_first_page()` 加载首屏数据。
+
+---
+
+### `command_handle(event)`
+
+处理来自工具栏的命令事件，并将其转为 `dispatch` 派发出去。
+
+```js
+this.toolbar_w.bind('command', this.command_handle.bind(this));
+```
+
+---
+
+### `async handle_click(rw, event)`
+
+处理单个记录项的点击事件。
+
+#### 功能：
+- 阻止事件冒泡。
+- 取消上一个选中项的高亮样式。
+- 设置当前项为选中状态并添加 `selected_record` CSS 类。
+- 打印日志并派发 `record_click` 事件，携带 `user_data`。
+
+> `rw.user_data` 存储的是该记录的原始数据对象。
+
+---
+
+### `async dataHandle(d)`
+
+处理从 `loader` 返回的数据包，并渲染到界面。
+
+#### 参数：
+- `d`: 数据对象，格式如下：
+  ```js
+  {
+    rows: [...],         // 数据数组
+    add_page: Number,    // 添加到哪一页
+    delete_page: Number, // （可选）需删除的页码（用于翻页替换）
+    pos_rate: Number     // 滚动位置比例（0~1）
+  }
+  ```
+
+#### 行为逻辑：
+- 若是向前翻页（非最大页），则反转数据顺序以便插入顶部。
+- 使用 `widgetBuild(record_view, parent, data)` 动态生成每个记录 widget。
+- 绑定点击事件。
+- 设置 `data-page` 属性用于后续删除。
+- 插入至 `main` 容器开头或末尾。
+- 如有 `delete_page`，调用 `delete_page()` 清理旧页。
+
+---
+
+### `delete_page(page)`
+
+删除指定页码的所有 DOM 元素及其 widget。
+
+#### 实现方式：
+- 查询所有 `[data-page="X"]` 的元素。
+- 获取其关联的 `bricks_widget` 实例。
+- 从 `main` 中移除对应 widget。
+
+---
+
+### `create_main_widget()`
+
+重新创建主内容区域（`DynamicColumn`），通常在刷新或重置布局时调用。
+
+```js
+this.main = new bricks.DynamicColumn({
+  width: "100%",
+  col_cwidth: this.col_cwidth,
+  mobile_cols: this.mobile_cols || 2
+});
+```
+
+---
+
+### `async show_with_data(data)`
+
+直接传入本地数据进行展示（绕过 `data_url` 请求）。
+
+> ⚠️ 注意：目前代码中存在错误，应为 `await this.load_first_page(params);` 而不是 `await load_first_page(params);`
+
+#### 正确实现建议：
+```js
+async show_with_data(data){
+  this.data = data;
+  this.data_url = null;
+  await this.load_first_page(); // 不需要参数
+}
+```
+
+---
+
+### `async load_first_page(params)`
+
+加载第一页数据。
+
+#### 流程：
+1. 显示加载动画（`Running` 组件）。
+2. 检查是否已在加载中，避免重复请求。
+3. 合并 `data_params` 与传入的 `params`。
+4. 调用 `loader.loadData()` 获取数据。
+5. 成功后清空主容器并调用 `dataHandle(d)`。
+6. 出错时打印调试信息。
+7. 最终隐藏加载动画，释放锁。
+
+---
+
+### `async load_previous_page()`
+
+向上滚动触底时加载前一页。
+
+- 自动计算滚动位置并恢复。
+- 支持 `pos_rate` 定位。
+- 错误时仅输出 debug 日志。
+
+---
+
+### `async load_next_page()`
+
+向下滚动触底时加载下一页。
+
+- 类似于 `load_previous_page`，但加载下一页。
+- 注释掉的 `scrollTop` 表示暂未启用精确滚动定位。
+
+---
+
+## 内部机制
+
+### 分页加载策略
+
+利用 `bricks.PageDataLoader` 实现智能分页：
+
+- 支持双向分页（上一页 / 下一页）。
+- 支持缓存控制（`cache_pages`）。
+- 数据按“页”组织，可通过 `data-page` 属性追踪来源。
+
+### 滚动加载触发
+
+通过 `VScrollPanel` 的两个事件实现无限滚动：
+
+| 事件 | 触发条件 |
+|------|----------|
+| `min_threshold` | 滚动到顶部附近 → 加载前一页 |
+| `max_threshold` | 滚动到底部附近 → 加载下一页 |
+
+绑定方式：
+```js
+this.container.bind('min_threshold', this.load_previous_page.bind(this));
+this.container.bind('max_threshold', this.load_next_page.bind(this));
+```
+
+---
+
+## 使用示例
+
+### 基本用法
+
+```js
+var cols = new bricks.Cols({
+  title: "Latest Articles",
+  description: "A list of recent posts.",
+  data_url: "/api/articles",
+  data_params: { category: "tech" },
+  page_rows: 10,
+  cache_limit: 5,
+  col_cwidth: "1fr",
+  mobile_cols: 2,
+  record_view: {
+    type: "CardView",
+    fields: ["title", "summary", "image"]
+  }
+});
+
+cols.bind("record_click", function(data) {
+  console.log("Selected:", data);
+});
+
+document.body.appendChild(cols.dom_element);
+```
+
+### 手动加载本地数据
+
+```js
+cols.show_with_data({
+  rows: [
+    {id: 1, name: "Item 1"},
+    {id: 2, name: "Item 2"}
+  ]
+});
+```
+
+---
+
+## 注意事项
+
+1. **性能优化**：只保留可视区域附近的页面，其他页面可手动卸载。
+2. **内存管理**：长时间运行应用应注意 `cache_limit` 设置，避免内存泄漏。
+3. **事件绑定**：确保 `handle_click` 使用 `.bind(this, w)` 正确绑定上下文。
+4. **CSS 样式**：
+   - `.selected_record`：用于标记选中项，请在 CSS 中定义高亮样式。
+   - `.filler`：应用于 `container`，可能影响背景或间距。
+
+---
+
+## 注册信息
+
+```js
+bricks.Factory.register('Cols', bricks.Cols);
+```
+
+可在模板中通过 `<widget type="Cols" ...>` 方式声明使用。
+
+---
+
+## 版本信息
+
+- **作者**：Bricks Framework Team
+- **最后更新**：根据代码推断为现代异步 JS 架构（ES6+）
+- **兼容性**：需支持 Promise、async/await、Custom Elements
+
+---
+
+## 相关组件
+
+| 组件 | 作用 |
+|------|------|
+| `bricks.PageDataLoader` | 提供分页数据加载能力 |
+| `bricks.VScrollPanel` | 提供滚动检测与阈值事件 |
+| `bricks.DynamicColumn` | 实现响应式多列布局 |
+| `bricks.widgetBuild` | 动态构建子组件的核心函数 |
+
+---
+
+✅ **文档完成度**：完整覆盖功能、接口、流程与使用方式。  
+🔧 **待修复问题**：`show_with_data` 方法中对 `load_first_page` 的调用缺少 `this.` 上下文。
\ No newline at end of file
diff --git a/aidocs/conform.md b/aidocs/conform.md
new file mode 100644
index 0000000..7eb8fd3
--- /dev/null
+++ b/aidocs/conform.md
@@ -0,0 +1,249 @@
+# `bricks.Conform` 技术文档
+
+> 一个基于 `bricks.PopupWindow` 的确认对话框类，用于展示消息并提供“确认”与“取消”操作选项。
+
+---
+
+## 概述
+
+`bricks.Conform` 是 `bricks` UI 框架中的一个模态弹窗组件，继承自 `bricks.PopupWindow`。它被设计用于在用户执行关键操作前进行确认，例如删除数据或提交表单。该组件自动显示，并包含可自定义的确认/取消按钮，支持国际化文本和事件回调。
+
+---
+
+## 类定义
+
+```javascript
+class bricks.Conform extends bricks.PopupWindow
+```
+
+---
+
+## 构造函数
+
+### `constructor(opts)`
+
+初始化一个 `Conform` 实例。
+
+#### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `opts` | Object | 配置选项对象，继承自 `PopupWindow` 并扩展以下属性： |
+
+##### 扩展配置项 (`opts`)
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `message` | String | 必填 | 要显示的消息内容，支持换行和国际化（i18n）。 |
+| `timeout` | Number | `0` (自动覆盖为 0) | 弹窗自动关闭时间（毫秒），此组件中强制设为 `0`，即不自动关闭。 |
+| `auto_open` | Boolean | `true` (自动设置) | 是否在创建后立即打开弹窗，此处固定为 `true`。 |
+| `conform` | Object | 可选 | “确认”按钮的自定义配置，如标签、事件等。 |
+| `discard` | Object | 可选 | “取消”按钮的自定义配置。 |
+
+> ⚠️ 注意：构造函数内部会强制设置 `opts.timeout = 0` 和 `opts.auto_open = true`，以确保用户必须手动选择操作。
+
+#### 示例
+
+```javascript
+var confirmDialog = new bricks.Conform({
+    message: "确定要删除此文件吗？",
+    conform: {
+        label: "删除",
+        handler: function(){ console.log("已确认"); }
+    },
+    discard: {
+        label: "保留"
+    }
+});
+```
+
+---
+
+## 方法说明
+
+### `create_conform()`
+
+创建主容器布局并将消息区域与工具栏添加进去。
+
+- 使用 `VBox` 布局占满整个窗口。
+- 调用 `create_message()` 和 `create_toolbar()` 分别构建内容区与操作区。
+- 将整体布局通过 `add_widget()` 添加到弹窗中。
+
+---
+
+### `create_message(widget)`
+
+创建消息显示区域，支持长文本滚动和居中对齐。
+
+#### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `widget` | `bricks.VBox` | 容器部件，用于承载消息内容。 |
+
+#### 内部结构
+
+1. 创建一个 `Filler` 占位符，允许内容拉伸填充。
+2. 在 `Filler` 中嵌入 `VScrollPanel` 支持垂直滚动。
+3. 添加 `Text` 组件显示消息：
+   - 启用文本换行 (`wrap: true`)
+   - 水平居中对齐 (`halign: 'middle'`)
+   - 支持国际化 (`i18n: true`)
+
+---
+
+### `create_toolbar(widget)`
+
+创建底部操作工具栏，包含“确认”和“取消”两个按钮。
+
+#### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `widget` | `bricks.VBox` | 容器部件，用于添加工具栏。 |
+
+#### 工具栏配置
+
+使用 `bricks.IconTextBar` 创建图标+文字按钮栏：
+
+| 按钮名称 | 图标 | 默认标签 | 自定义来源 |
+|---------|------|----------|------------|
+| `conform` | `imgs/conform.svg` | "Conform" | `this.opts.conform` |
+| `discard` | `imgs/cancel.svg` | "Discard" | `this.opts.discard` |
+
+> ✅ 所有自定义属性将通过 `bricks.extend()` 合并到默认配置中。
+
+#### 事件绑定
+
+- `conform` → 触发 `conform_hndl`
+- `discard` → 触发 `discard_hndl`
+
+---
+
+### `conform_hndl(event)`
+
+“确认”按钮点击处理函数。
+
+#### 行为
+
+1. 调用 `this.dismiss()` 关闭弹窗。
+2. 触发名为 `'conformed'` 的自定义事件，供外部监听。
+
+#### 示例监听
+
+```javascript
+confirmDialog.on('conformed', function(){
+    // 执行确认逻辑
+});
+```
+
+---
+
+### `discard_hndl(event)`
+
+“取消”按钮点击处理函数。
+
+#### 行为
+
+1. 调用 `this.dismiss()` 关闭弹窗。
+2. 触发名为 `'cancelled'` 的自定义事件。
+
+#### 示例监听
+
+```javascript
+confirmDialog.on('cancelled', function(){
+    // 执行取消后的逻辑
+});
+```
+
+---
+
+## 事件列表
+
+| 事件名 | 触发时机 | 携带数据 |
+|-------|----------|--------|
+| `conformed` | 用户点击“确认”按钮后 | 无 |
+| `cancelled` | 用户点击“取消”按钮后 | 无 |
+
+可通过 `.on(event, handler)` 或 `.bind(event, handler)` 注册监听。
+
+---
+
+## 注册信息
+
+```javascript
+bricks.Factory.register('Conform', bricks.Conform);
+```
+
+- 通过工厂模式注册名称为 `'Conform'` 的可实例化组件。
+- 可通过 `bricks.Factory.create('Conform', options)` 动态创建实例。
+
+---
+
+## 布局结构图
+
+```plaintext
+PopupWindow
+└── VBox (100% x 100%)
+    ├── Filler
+    │   └── VScrollPanel
+    │       └── Text (消息内容)
+    └── IconTextBar
+        ├── [✔] Conform 按钮
+        └── [✖] Discard 按钮
+```
+
+---
+
+## 样式与资源依赖
+
+- **图标资源路径**：
+  - 确认图标：`bricks_resource('imgs/conform.svg')`
+  - 取消图标：`bricks_resource('imgs/cancel.svg')`
+- 使用 `i18n: true`，需配合国际化语言包解析多语言文本。
+
+---
+
+## 使用建议
+
+✅ 推荐场景：
+
+- 删除、覆盖、退出等危险操作前的二次确认。
+- 需要用户明确响应的操作流程中断点。
+
+❌ 不适用场景：
+
+- 非阻塞性提示（应使用 Toast 或 Banner）。
+- 需长时间停留的信息展示（考虑使用普通窗口）。
+
+---
+
+## 完整示例
+
+```javascript
+var dialog = new bricks.Conform({
+    message: "您确定要退出编辑模式吗？未保存的内容将会丢失。",
+    conform: { label: "退出", style: "danger" },
+    discard: { label: "继续编辑" }
+});
+
+dialog.on('conformed', function(){
+    window.location.href = "/home";
+});
+
+dialog.on('cancelled', function(){
+    console.log("用户选择保留");
+});
+```
+
+---
+
+## 版本信息
+
+- **框架版本**：`bricks.js`
+- **组件作者**：未知（基于命名空间推断）
+- **最后更新**：根据代码逻辑推断为现代 ES6+ 风格实现
+
+--- 
+
+📌 *文档生成于：2025年4月*
\ No newline at end of file
diff --git a/aidocs/continueaudio.md b/aidocs/continueaudio.md
new file mode 100644
index 0000000..a8c6348
--- /dev/null
+++ b/aidocs/continueaudio.md
@@ -0,0 +1,314 @@
+# `ContinueAudioPlayer` 技术文档
+
+> 一个基于 Web Audio API 的连续音频播放器组件，支持流式播放、音量控制、暂停/恢复、静音切换和事件回调。
+
+---
+
+## 概述
+
+`bricks.ContinueAudioPlayer` 是一个继承自 `bricks.VBox` 的音频播放类，专为在浏览器中实现无缝连续音频播放而设计。它使用 Web Audio API 解码并播放 Base64 编码或 ArrayBuffer 格式的音频数据，并支持动态控制播放状态与音量。
+
+该组件适用于需要精确时间控制的语音合成（TTS）、实时音频流处理等场景。
+
+---
+
+## 类定义
+
+```js
+class ContinueAudioPlayer extends bricks.VBox
+```
+
+注册名称：`'ContinueAudioPlayer'`  
+注册方式：
+```js
+bricks.Factory.register('ContinueAudioPlayer', bricks.ContinueAudioPlayer);
+```
+
+---
+
+## 构造函数
+
+### `constructor(options)`
+
+初始化播放器实例。
+
+#### 参数
+
+| 参数名     | 类型   | 描述 |
+|----------|--------|------|
+| `options.ws_url` | `string` | WebSocket 地址（当前未实际使用，保留字段） |
+| `options.onStart` | `Function` | 音频开始播放时触发的回调函数 |
+| `options.onEnd` | `Function` | 当前音频片段结束播放时触发 |
+| `options.onPause` | `Function` | 暂停播放时触发 |
+| `options.onResume` | `Function` | 恢复播放时触发 |
+| `options.onVolumeChange` | `Function` | 音量变化时触发，参数为新音量值 |
+
+#### 示例
+
+```js
+const player = new bricks.ContinueAudioPlayer({
+    ws_url: 'wss://example.com/audio',
+    onStart: () => console.log('Audio started'),
+    onEnd: () => console.log('Audio ended'),
+    onPause: () => console.log('Paused'),
+    onResume: () => console.log('Resumed'),
+    onVolumeChange: (vol) => console.log(`Volume: ${vol}`)
+});
+```
+
+---
+
+## 属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `audioContext` | `AudioContext` | Web Audio 上下文对象 |
+| `gainNode` | `GainNode` | 控制音量的增益节点 |
+| `nextStartTime` | `Number` | 下一段音频应开始播放的时间（以秒为单位） |
+| `started` | `Boolean` | 是否已成功初始化音频上下文 |
+| `muted` | `Boolean` | 当前是否处于静音状态 |
+| `volume` | `Number` | 当前音量（范围：0.0 - 1.0） |
+| `ws_url` | `String` | 存储传入的 WebSocket URL（目前仅作存储用途） |
+| `options` | `Object` | 用户传入的配置选项 |
+
+---
+
+## 方法
+
+### `initAudioContext()`
+
+创建并初始化 `AudioContext` 和 `GainNode`，准备音频播放环境。
+
+- 若上下文已被关闭，则可通过调用此方法重新激活。
+- 自动设置初始增益值为 `this.volume`。
+- 更新 `nextStartTime` 为当前时间，确保后续音频从正确时间点开始。
+
+> ⚠️ 注意：由于浏览器策略限制，**必须在用户交互（如点击）后才能创建或恢复 AudioContext**。
+
+---
+
+### `base64ToArrayBuffer(base64) → ArrayBuffer`
+
+将 Base64 字符串转换为 `ArrayBuffer`，用于 Web Audio API 解码。
+
+#### 参数
+
+| 参数名 | 类型 | 描述 |
+|-------|------|------|
+| `base64` | `string` | Base64 编码的二进制音频数据 |
+
+#### 返回值
+
+- `{ArrayBuffer}`：可用于 `decodeAudioData` 的原始二进制缓冲区。
+
+#### 示例
+
+```js
+const buffer = player.base64ToArrayBuffer("UklGRiQAAABXQVZFZm...");
+```
+
+---
+
+### `handleAudioTrack(arrayBuffer)`
+
+解码并播放一段音频数据。
+
+#### 参数
+
+| 参数名 | 类型 | 描述 |
+|-------|------|------|
+| `arrayBuffer` | `ArrayBuffer` | 包含编码音频数据的二进制缓冲区（如 WAV、MP3 等） |
+
+#### 行为说明
+
+1. 使用 `audioContext.decodeAudioData()` 异步解码音频。
+2. 创建 `AudioBufferSourceNode` 并连接到增益节点。
+3. 在合适的时间点开始播放（避免重叠）：
+   - 开始时间为 `Math.max(currentTime, this.nextStartTime)`
+4. 更新 `nextStartTime` 为本次播放结束时间，保证下段音频接续播放。
+5. 触发 `onStart` 回调。
+6. 播放结束后触发 `onEnd` 回调。
+
+#### 错误处理
+
+若解码失败，会在控制台输出错误日志：
+
+```text
+Error decoding audio data: [Error]
+```
+
+---
+
+### `pauseAudio()`
+
+暂停所有正在播放的音频。
+
+- 调用 `audioContext.suspend()` 挂起上下文。
+- 成功后触发 `onPause` 回调。
+
+> 📝 仅当 `audioContext.state === 'running'` 时有效。
+
+---
+
+### `resumeAudio()`
+
+恢复被暂停的音频播放。
+
+- 调用 `audioContext.resume()` 恢复上下文运行。
+- 成功后触发 `onResume` 回调。
+
+> 📝 仅当 `audioContext.state === 'suspended'` 时有效。
+
+---
+
+### `restart()`
+
+停止当前播放，关闭音频上下文，并重新初始化，实现“重新开始”。
+
+#### 行为流程
+
+1. 如果上下文存在且未关闭，先调用 `close()`。
+2. 关闭完成后调用 `initAudioContext()` 重建上下文。
+3. 重置播放时间线。
+
+> ✅ 可用于重置播放状态或应对长时间运行后的资源释放问题。
+
+---
+
+### `setVolume(value)`
+
+设置播放音量。
+
+#### 参数
+
+| 参数名 | 类型 | 范围 | 描述 |
+|-------|------|------|------|
+| `value` | `number` | `0.0 ~ 1.0` | 目标音量值 |
+
+#### 功能
+
+- 自动限制输入值在 `[0, 1]` 范围内。
+- 更新 `this.volume`。
+- 如果已初始化 `gainNode`，则更新其 `gain.value`（若已静音则保持为 0）。
+- 触发 `onVolumeChange` 事件。
+
+#### 示例
+
+```js
+player.setVolume(0.75); // 设置音量为 75%
+```
+
+---
+
+### `toggleMute()`
+
+切换静音状态。
+
+- 若当前非静音，则进入静音状态（`gain.value = 0`）。
+- 若当前静音，则恢复至原音量（`gain.value = this.volume`）。
+- 切换后更新 `this.muted` 并触发 `onVolumeChange`。
+
+---
+
+### `emit(eventName, ...args)`
+
+触发指定事件回调（如果定义了对应函数）。
+
+#### 参数
+
+| 参数名 | 类型 | 描述 |
+|-------|------|------|
+| `eventName` | `string` | 回调函数名（对应 `options[eventName]`） |
+| `...args` | any | 传递给回调的参数 |
+
+#### 示例
+
+```js
+this.emit('onStart'); // 调用 options.onStart()
+```
+
+---
+
+## 使用示例
+
+```js
+// 创建播放器实例
+const audioPlayer = new bricks.ContinueAudioPlayer({
+    onStart: () => console.log("▶️ 开始播放"),
+    onEnd: () => console.log("⏹️ 播放结束"),
+    onVolumeChange: (v) => console.log(`🔊 音量: ${v}`)
+});
+
+// 假设你有一段 Base64 音频数据
+const base64Audio = "UklGRiQAAABXQVZFZm1...";
+const buffer = audioPlayer.base64ToArrayBuffer(base64Audio);
+
+// 播放音频
+audioPlayer.handleAudioTrack(buffer);
+
+// 控制操作
+audioPlayer.setVolume(0.5);        // 调整音量
+audioPlayer.toggleMute();          // 切换静音
+audioPlayer.pauseAudio();          // 暂停
+audioPlayer.resumeAudio();         // 恢复
+audioPlayer.restart();             // 重启播放器
+```
+
+---
+
+## 浏览器兼容性
+
+| 浏览器 | 支持情况 |
+|--------|----------|
+| Chrome | ✅ 支持 |
+| Firefox | ✅ 支持 |
+| Safari | ⚠️ 需要 `webkitAudioContext` 兼容写法（已内置处理） |
+| Edge | ✅ 支持 |
+| iOS Safari | ✅（注意自动播放策略） |
+
+> 🔐 **注意**：出于安全策略，大多数现代浏览器要求 **用户手势（如点击）** 后才能启动音频上下文。
+
+---
+
+## 注意事项
+
+1. **自动播放限制**  
+   大多数浏览器禁止页面加载时自动播放音频。建议在用户点击事件中初始化或调用 `handleAudioTrack`。
+
+2. **内存管理**  
+   长时间连续播放大量音频可能导致内存占用上升，请合理管理音频数据生命周期。
+
+3. **跨域音频数据**  
+   所有音频数据需满足同源策略或 CORS 要求，否则无法解码。
+
+4. **精度同步**  
+   利用 `AudioContext.currentTime` 实现高精度播放调度，适合多段连续播放场景。
+
+---
+
+## 图解工作流程
+
+```
+[Base64] 
+   ↓ base64ToArrayBuffer()
+[ArrayBuffer]
+   ↓ handleAudioTrack()
+decodeAudioData() → AudioBuffer
+   ↓ createBufferSource()
+[Source Node] → gainNode → destination
+   ↑
+startTime = max(now, nextStartTime)
+   ↓
+nextStartTime += duration
+```
+
+---
+
+## 许可与归属
+
+© 2025 Bricks Framework. All rights reserved.  
+开源协议：请参考项目 LICENSE 文件。
+
+--- 
+
+📌 **提示**：结合 WebSocket 或 Fetch 流式传输，可实现 TTS 实时语音播报系统。
\ No newline at end of file
diff --git a/aidocs/countdown.md b/aidocs/countdown.md
new file mode 100644
index 0000000..0d4501e
--- /dev/null
+++ b/aidocs/countdown.md
@@ -0,0 +1,284 @@
+# Bricks 时间组件技术文档
+
+本模块提供两个基于 `bricks` 框架的时间显示类组件：`TimePassed`（计时器）和 `Countdown`（倒计时器），并包含一个通用的时间格式化工具函数。这些组件可用于构建需要时间展示功能的 UI 界面。
+
+---
+
+## 目录
+
+- [1. 核心工具函数](#1-核心工具函数)
+  - [`bricks.formatTime(seconds)`](#bricksformattimeseconds)
+- [2. TimePassed 类（正向计时器）](#2-timepassed-类正向计时器)
+  - [继承关系](#继承关系)
+  - [构造函数](#构造函数)
+  - [方法](#方法)
+- [3. Countdown 类（倒计时器）](#3-countdown-类倒计时器)
+  - [继承关系](#继承关系-1)
+  - [配置选项 (`opts`)](#配置选项-opts)
+  - [事件](#事件)
+  - [构造函数](#构造函数-1)
+  - [方法](#方法-1)
+- [4. 工厂注册](#4-工厂注册)
+- [5. 使用示例](#5-使用示例)
+
+---
+
+## 1. 核心工具函数
+
+### `bricks.formatTime(seconds)`
+
+将秒数转换为 `HH:MM:SS` 格式的字符串，不足两位用前导零填充。
+
+#### 参数
+
+| 参数名    | 类型   | 描述         |
+|---------|--------|--------------|
+| seconds | number | 时间（以秒为单位） |
+
+#### 返回值
+
+- `{string}`：格式化后的时间字符串，格式为 `HH:MM:SS`。
+
+#### 示例
+
+```js
+bricks.formatTime(3661); // 输出 "01:01:01"
+bricks.formatTime(59);   // 输出 "00:00:59"
+```
+
+#### 实现说明
+
+- 小时 = `Math.floor(seconds / 3600)`
+- 分钟 = `Math.floor((seconds % 3600) / 60)`
+- 秒 = `seconds % 60`
+- 每部分使用 `.padStart(2, '0')` 补齐至两位数字。
+
+---
+
+## 2. TimePassed 类（正向计时器）
+
+用于从 0 开始递增显示已过去的时间（如“00:00:05”表示运行了 5 秒）。
+
+### 继承关系
+
+```js
+class TimePassed extends bricks.VBox
+```
+
+> 继承自 `bricks.VBox`，作为容器可包含子控件。
+
+---
+
+### 构造函数
+
+```js
+new bricks.TimePassed(opts)
+```
+
+#### 参数
+
+| 参数名     | 类型   | 是否必需 | 描述                     |
+|----------|--------|----------|--------------------------|
+| opts     | object | 是       | 配置对象                 |
+| opts.text_rate | any  | 否       | 文本渲染速率或样式参数，传递给内部 Text 组件 |
+
+> ⚠️ 注意：当前代码中存在潜在 bug —— 使用了未定义变量 `this.t` 和 `this.text_rate`，应为 `opts.text_rate` 并初始化文本内容为 `formatTime(this.seconds)`。
+
+✅ **建议修复后的构造函数片段：**
+
+```js
+this.seconds = 0;
+this.text_w = new bricks.Text({
+    text: bricks.formatTime(this.seconds),
+    rate: opts.text_rate
+});
+this.add_widget(this.text_w);
+```
+
+---
+
+### 方法
+
+| 方法名       | 描述                                                         |
+|------------|--------------------------------------------------------------|
+| `start()`  | 启动计时器，每秒调用一次 `add_one_second()`，开始递增时间。       |
+| `stop()`   | 停止计时器，取消当前调度任务。                                   |
+
+#### `add_one_second()`
+
+私有方法，由 `schedule_once` 调度执行：
+
+- 每次使 `this.seconds += 1`
+- 更新显示文本
+- 自动重新调度下一次调用（形成循环）
+
+> 使用 `bind(this)` 确保上下文正确。
+
+⚠️ 若不停止，将持续运行。
+
+---
+
+## 3. Countdown 类（倒计时器）
+
+实现一个可配置的倒计时组件，在时间归零时触发事件。
+
+### 继承关系
+
+```js
+class Countdown extends bricks.VBox
+```
+
+> 同样继承自 `VBox` 容器组件。
+
+---
+
+### 配置选项 (`opts`)
+
+| 参数名        | 类型   | 是否必需 | 描述                                                                 |
+|-------------|--------|----------|----------------------------------------------------------------------|
+| limit_time  | string | 是       | 初始倒计时时间，格式支持 `"SS"`、`"MM:SS"` 或 `"HH:MM:SS"`               |
+| text_rate   | any    | 否       | 传入 Text 组件的渲染参数                                               |
+
+---
+
+### 事件
+
+| 事件名      | 触发条件                         | 数据参数 |
+|-----------|----------------------------------|--------|
+| `timeout` | 当倒计时结束（`this.seconds < 1`）时触发 | 无     |
+
+可通过 `this.dispatch('timeout')` 触发事件，供外部监听。
+
+---
+
+### 构造函数
+
+```js
+new bricks.Countdown(opts)
+```
+
+#### 功能说明
+
+1. 解析 `opts.limit_time` 字符串为小时、分钟、秒。
+2. 支持以下格式：
+   - `"30"` → 30 秒
+   - `"5:30"` → 5 分 30 秒
+   - `"1:30:45"` → 1 小时 30 分 45 秒
+3. 转换为总秒数存储在 `this.seconds`。
+4. 创建并添加 `Text` 组件用于显示时间。
+
+> ✅ 支持任意长度分割，但仅处理 1~3 段，其余情况默认按三段解析。
+
+---
+
+### 方法
+
+| 方法名              | 描述                                                                 |
+|-------------------|----------------------------------------------------------------------|
+| `start()`         | 启动倒计时，延迟 1 秒后调用 `time_down_second()` 开始递减。             |
+| `time_down_second()` | 私有方法：每次减少 1 秒，更新显示；若时间为 0，则触发 `timeout` 事件并终止。 |
+
+> 使用 `schedule_once(fn, delay)` 实现定时回调，形成递归倒计时。
+
+---
+
+## 4. 工厂注册
+
+为了支持动态创建组件实例，通过工厂模式注册两个类：
+
+```js
+bricks.Factory.register('Countdown', bricks.Countdown);
+bricks.Factory.register('TimePassed', bricks.TimePassed);
+```
+
+### 用途
+
+允许通过字符串名称动态创建组件，例如：
+
+```js
+let timer = bricks.Factory.create('TimePassed', { text_rate: 'high' });
+let cd = bricks.Factory.create('Countdown', { limit_time: '00:01:00' });
+```
+
+---
+
+## 5. 使用示例
+
+### 示例 1：创建并启动正向计时器
+
+```js
+let timePassed = new bricks.TimePassed({
+    text_rate: 'normal'
+});
+
+// 添加到页面或其他容器
+someContainer.add_widget(timePassed);
+
+// 开始计时
+timePassed.start();
+
+// 停止计时
+// timePassed.stop();
+```
+
+### 示例 2：创建倒计时器并监听超时事件
+
+```js
+let countdown = new bricks.Countdown({
+    limit_time: '00:00:10',  // 10 秒倒计时
+    text_rate: 'large'
+});
+
+countdown.on('timeout', function() {
+    console.log('倒计时结束！');
+    alert('时间到！');
+});
+
+someContainer.add_widget(countdown);
+countdown.start();  // 启动倒计时
+```
+
+### 示例 3：使用工厂创建组件
+
+```js
+let widget = bricks.Factory.create('Countdown', {
+    limit_time: '01:30:00'
+});
+
+widget.on('timeout', () => {
+    console.log('倒计时完成');
+});
+
+container.add_widget(widget);
+widget.start();
+```
+
+---
+
+## 注意事项与改进建议
+
+1. **Bug 修复建议**
+   - 在 `TimePassed` 构造函数中，`text: this.t` 应改为 `text: bricks.formatTime(this.seconds)`
+   - `rate: this.text_rate` 应为 `rate: opts.text_rate`
+
+2. **性能优化**
+   - 可考虑使用 `setInterval` 替代递归 `schedule_once`，但当前方式更灵活且兼容异步调度系统。
+
+3. **扩展性建议**
+   - 可增加 `pause()` 方法支持暂停/恢复。
+   - 提供 `getFormattedTime()` 公共方法获取当前时间字符串。
+
+4. **输入验证**
+   - 对 `limit_time` 的解析可加入非法值检测（如非数字）。
+
+---
+
+## 版本信息
+
+- 模块名：`bricks.time`
+- 作者：Bricks Framework Team
+- 最后更新：2025-04-05
+
+--- 
+
+📌 *本文档适用于 Bricks UI 框架 v1.x+*
\ No newline at end of file
diff --git a/aidocs/css.md b/aidocs/css.md
new file mode 100644
index 0000000..8ee4f95
--- /dev/null
+++ b/aidocs/css.md
@@ -0,0 +1,88 @@
+# CSS 多列布局配置文档
+
+本技术文档描述了一个用于定义多列布局样式的 JavaScript 对象 `css`，其中包含多列布局的样式配置。
+
+---
+
+## 概述
+
+该对象 `css` 用于存储与 CSS 多列布局相关的样式属性。当前仅定义了一个名为 `multicolumns` 的子对象，用于配置多列布局的宽度和间距。
+
+---
+
+## 配置结构
+
+```javascript
+var css = {
+    multicolumns: {
+        columnWidth: '350px',
+        colummGap: '10px'
+    }
+}
+```
+
+> ⚠️ 注意：`colummGap` 存在拼写错误，应为 `columnGap`。
+
+---
+
+## 属性说明
+
+### `multicolumns`
+
+一个包含多列布局相关 CSS 属性的对象。
+
+| 属性名        | 类型   | 默认值     | 描述 |
+|---------------|--------|------------|------|
+| `columnWidth` | 字符串 | `'350px'`  | 定义每列的宽度。此处设置为 `350px`，表示每列宽 350 像素。 |
+| `colummGap`   | 字符串 | `'10px'`   | ⚠️ **拼写错误**：应为 `columnGap`。用于设置列之间的间距，当前设置为 `10px`。 |
+
+---
+
+## 使用建议
+
+### 修正拼写错误
+
+建议将 `colummGap` 更正为 `columnGap`，以确保与标准 CSS 属性名称一致：
+
+```javascript
+var css = {
+    multicolumns: {
+        columnWidth: '350px',
+        columnGap: '10px'  // 已修正拼写
+    }
+}
+```
+
+### 实际应用示例
+
+可将此配置动态应用于 DOM 元素，例如：
+
+```javascript
+const element = document.getElementById('content');
+element.style.columnWidth = css.multicolumns.columnWidth;
+element.style.columnGap = css.multicolumns.columnGap;
+```
+
+或结合 CSSOM 使用：
+
+```css
+/* 等效的 CSS 写法 */
+#content {
+    column-width: 350px;
+    column-gap: 10px;
+}
+```
+
+---
+
+## 浏览器兼容性
+
+- `column-width` 和 `column-gap` 是 CSS Multi-column Layout Module 的一部分。
+- 现代浏览器普遍支持，但在旧版浏览器（如 IE）中不支持。
+- 推荐在使用时添加必要的厂商前缀或进行兼容性检测。
+
+---
+
+## 总结
+
+该配置对象提供了一种通过 JavaScript 管理多列布局样式的简便方式。建议修复属性名拼写错误，并在生产环境中结合实际需求进行扩展和封装。
\ No newline at end of file
diff --git a/aidocs/datagrid.md b/aidocs/datagrid.md
new file mode 100644
index 0000000..a04c4db
--- /dev/null
+++ b/aidocs/datagrid.md
@@ -0,0 +1,434 @@
+# `bricks.DataGrid` 技术文档
+
+> **基于 `bricks.js` 框架的可冻结列数据表格组件**
+
+---
+
+## 概述
+
+`bricks.DataGrid` 是一个功能丰富的前端数据网格组件，支持：
+- 冻结列（固定左侧列）
+- 虚拟滚动与分页加载
+- 动态字段渲染（通过 `uitype` 和 `uioptions`）
+- 行选择、点击事件处理
+- 工具栏、迷你表单集成
+- 多语言支持（i18n）
+
+该组件继承自 `bricks.VBox`，采用模块化设计，结合 `bricks.Row` 实现每行数据的封装和交互。
+
+---
+
+## 类结构
+
+### 1. `bricks.Row`
+
+表示数据网格中的一行记录。
+
+#### 构造函数：`constructor(dg, rec)`
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `dg` | `bricks.DataGrid` | 所属的数据网格实例 |
+| `rec` | `Object` | 当前行的数据对象 |
+
+**初始化内容：**
+- 复制数据：`this.data = objcopy(rec)`
+- 初始化列容器：`freeze_cols`, `normal_cols`
+- 创建列控件：调用 `create_col_widgets()` 分别生成冻结列和普通列
+- 设置宽度样式
+- 绑定点击处理器
+
+#### 属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `dg` | `DataGrid` | 所属的数据网格对象 |
+| `data` | `Object` | 当前行原始数据副本 |
+| `freeze_cols` | `Array<bricks.Widget>` | 冻结列中的控件列表 |
+| `normal_cols` | `Array<bricks.Widget>` | 非冻结列中的控件列表 |
+| `name_widgets` | `Object` | 字段名 → 控件映射表 |
+| `click_handler` | `Function` | 点击事件处理器（绑定到所属 DataGrid） |
+| `freeze_row` | `bricks.HBox` 或 `null` | 包含所有冻结列控件的水平布局容器 |
+| `normal_row` | `bricks.HBox` 或 `null` | 包含所有非冻结列控件的水平布局容器 |
+
+#### 方法
+
+##### `create_col_widgets(fields, cols)` → `bricks.HBox|null`
+
+根据字段定义创建对应的 UI 控件，并放入指定数组中。
+
+**参数：**
+- `fields`: 字段配置数组
+- `cols`: 输出控件数组（引用传递）
+
+**逻辑流程：**
+1. 遍历每个字段 `f`
+2. 合并默认选项：
+   ```js
+   {
+     name: f.name,
+     label: f.label,
+     uiype: f.uitype,
+     width: f.width,
+     required: true,
+     row_data: objcopy(this.data),
+     readonly: true
+   }
+   ```
+3. 根据 `uitype` 创建不同控件：
+   - `'button'`: 使用 `bricks.Button`，绑定 `button_click`
+   - 其他类型：使用 `bricks.viewFactory(opts, this.data)`
+4. 为控件设置样式（flex 布局、最小宽度）
+5. 将控件加入 `cols` 数组及 `name_widgets` 映射
+6. 最终返回一个包含这些控件的 `HBox`
+
+**返回值：**
+- 成功时返回 `HBox` 容器
+- 若无字段则返回 `null`
+
+---
+
+##### `button_click(event)`
+
+按钮点击回调函数。
+
+**行为：**
+- 临时重写 `getValue()` 方法，使其返回整行数据
+- 准备动作描述符 `desc`（含 action、params、datawidget 等）
+- 触发全局处理器 `universal_handler`
+
+> ⚠️ 注意：此方法在 `Button` 上下文中执行（通过 `.bind(w)` 绑定）
+
+---
+
+##### `selected()`
+
+将当前行设为“已选”状态（视觉高亮）。
+
+**操作：**
+- 遍历所有列控件，移除 `'selected'` CSS 类
+
+##### `unselected()`
+
+取消当前行的选择状态。
+
+**操作：**
+- 添加 `'selected'` CSS 类至所有列控件
+
+##### `toogle_select(e, f)`
+
+手动切换 DOM 元素的选中类。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `e` | `HTMLElement` | 要操作的元素 |
+| `f` | `Boolean` | 是否添加 `'selected'` 类 |
+
+---
+
+### 2. `bricks.DataGrid` （主类）
+
+继承自 `bricks.VBox`，实现完整的数据表格功能。
+
+#### 构造函数：`constructor(opts)`
+
+**参数 `opts` 支持以下属性：**
+
+| 属性 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `dataurl` | `String` | 否 | - | 数据接口 URL（用于异步加载） |
+| `method` | `String` | 否 | `'GET'` | 请求方式 |
+| `params` | `Object` | 否 | `{}` | 请求参数 |
+| `title` | `String` | 否 | - | 表格标题（显示为 `Title1`） |
+| `description` | `String` | 否 | - | 表格描述文本 |
+| `show_info` | `Boolean` | 否 | `false` | 是否显示信息栏 |
+| `miniform` | `Object` | 否 | - | 查询条件迷你表单配置 |
+| `toolbar` | `Object` | 否 | - | 工具栏按钮配置 |
+| `row_height` | `Number/String` | 否 | `'auto'` | 表头行高度 |
+| `header_css` | `String` | 否 | `'grid_header'` | 表头 CSS 类名 |
+| `body_css` | `String` | 否 | `'grid_body'` | 表体 CSS 类名 |
+| `fields` | `Array<Object>` | 是 | - | 字段定义数组（见下文） |
+| `check` | `Boolean` | 否 | `false` | 是否显示复选框列 |
+| `lineno` | `Boolean` | 否 | `false` | 是否显示序号列 |
+| `admin` | `Any` | 否 | - | 管理员权限标志（预留扩展） |
+
+#### 字段定义 (`fields`) 结构
+
+每个字段对象包含：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `name` | `String` | 字段名（对应数据键） |
+| `label` | `String` | 显示标签（支持 i18n） |
+| `datatype` | `String` | 数据类型（如 string, int, date） |
+| `uitype` | `String` | 控件类型（text, number, button, checkbox 等） |
+| `uioptions` | `Object` | 控件额外配置项 |
+| `freeze` | `Boolean` | 是否冻结（固定在左侧） |
+| `width` | `Number/String` | 列宽（单位 px） |
+
+> 特殊字段自动插入：
+> - `_check`: 复选框列（当 `check=true`）
+> - `_lineno`: 序号列（当 `lineno=true`）
+
+---
+
+#### 主要属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `loading` | `Boolean` | 是否正在加载数据 |
+| `select_row` | `bricks.Row` | 当前选中行对象 |
+| `dataurl`, `method`, `params` | `String/Object` | 数据请求配置 |
+| `fields` | `Array` | 所有字段定义 |
+| `freeze_fields` / `normal_fields` | `Array` | 分离后的冻结/非冻结字段列表 |
+| `freeze_width` / `normal_width` | `Number` | 冻结区与主体区域总宽度（px） |
+| `freeze_part`, `normal_part` | `VBox` | 左右两部分容器 |
+| `freeze_header`, `normal_header` | `HBox` | 表头容器 |
+| `freeze_body`, `normal_body` | `VScrollPanel` | 表体滚动容器 |
+| `loader` | `BufferedDataLoader` | 缓冲式数据加载器 |
+| `miniform` | `MiniForm` | 查询表单 |
+| `toolbar` | `Toolbar` | 工具栏 |
+
+---
+
+#### 核心方法
+
+##### `create_parts()`
+
+初始化整个表格结构，包括：
+1. 分离字段为 `freeze_fields` 和 `normal_fields`
+2. 计算各区域宽度
+3. 创建左右两个垂直容器（带滚动）
+4. 构建表头（调用 `create_header()`）
+5. 设置同步滚动机制（`coscroll`）
+
+> ✅ 如果启用了 `check` 或 `lineno`，会自动插入特殊字段。
+
+---
+
+##### `create_header()`
+
+创建表头单元格，使用 `bricks.Text` 显示字段 `label` 或 `name`。
+
+- 每个文本控件设置 `flex` 样式以匹配列宽
+- 添加 `column_no` 属性到 DOM 元素（格式：`f0`, `n1`...），便于后续定位
+
+---
+
+##### `add_rows(records, direction)` 
+
+批量添加多行数据。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `records` | `Array<Object>` | 数据记录数组 |
+| `direction` | `'up' \| 'down'` | 添加方向（默认 `'down'`） |
+
+内部循环调用 `add_row()`。
+
+---
+
+##### `add_row(data, index)` 
+
+添加单行数据。
+
+**步骤：**
+1. 实例化 `new bricks.Row(this, data)`
+2. 将其 `freeze_row` 和 `normal_row` 分别加入左右容器
+3. 可指定插入位置（`index`）
+
+---
+
+##### `clear_data()` 
+
+清空所有行数据并重置选中行。
+
+- 清除 `freeze_body` 和 `normal_body` 中的控件
+- 设置 `selected_row = null`
+
+---
+
+##### `del_old_rows(cnt, direction)` 
+
+删除旧的若干行（用于虚拟滚动优化）。
+
+| 参数 | 说明 |
+|------|------|
+| `cnt` | 删除数量 |
+| `direction` | `'up'`（顶部删除）或 `'down'`（底部删除） |
+
+---
+
+##### `loadData(params)` 
+
+重新加载数据（通常由外部触发）。
+
+委托给 `this.loader.loadData(params)`
+
+---
+
+##### `miniform_input(event)` 
+
+监听迷你表单输入事件，自动调用 `loadData()`。
+
+---
+
+##### `command_handle(event)` 
+
+工具栏命令处理钩子（需用户自行覆盖实现）。
+
+---
+
+##### `coscroll(event)` 
+
+实现左右两列区域的垂直滚动同步。
+
+**原理：**
+- 监听任一侧 `VScrollPanel` 的 `scroll` 事件
+- 同步另一侧的 `scrollTop`
+
+> 保证冻结列与主表体垂直对齐
+
+---
+
+##### `load_previous_data()` / `load_next_data()`
+
+响应滚动到底部/顶部阈值时，加载前一页/后一页数据。
+
+内部调用 `this.loader.previousPage()` 或 `nextPage()`
+
+> 通过 `min_threshold` / `max_threshold` 事件绑定触发
+
+---
+
+##### `click_handler(row, event)` 
+
+行内控件点击统一处理器。
+
+**行为：**
+1. 取消之前选中行的高亮
+2. 高亮当前行（调用 `row.selected()`）
+3. 触发 `row_click` 自定义事件
+4. 输出调试日志
+
+> 此函数作为 `bind` 上下文传入每一行控件
+
+---
+
+## 事件系统
+
+| 事件名 | 触发时机 | 传递参数 |
+|-------|---------|--------|
+| `row_click` | 用户点击某一行 | `bricks.Row` 实例 |
+| `input` (from miniform) | 迷你表单值变化 | event 对象 |
+| `command` (from toolbar) | 工具栏按钮被点击 | command 名称等 |
+
+---
+
+## 样式类说明（CSS Classes）
+
+| 类名 | 应用元素 | 用途 |
+|------|----------|------|
+| `datagrid` | 外层容器 | 主体样式 |
+| `datagrid-grid` | 主 `HBox` | 网格布局容器 |
+| `datagrid-left` | 冻结区 `VBox` | 左侧固定列容器 |
+| `datagrid-right` | 主体区 `VBox` | 右侧可滚动列容器 |
+| `grid_header` | 表头 `HBox` | 表头样式 |
+| `datagrid-body` | `VScrollPanel` | 表体滚动区域样式 |
+| `selected` | 单元格/行 | 高亮选中状态 |
+
+---
+
+## 注册与使用
+
+```js
+// 注册组件工厂
+bricks.Factory.register('DataGrid', bricks.DataGrid);
+```
+
+### 示例用法
+
+```js
+var grid = new bricks.DataGrid({
+  title: "用户列表",
+  dataurl: "/api/users",
+  method: "POST",
+  params: { dept: "sales" },
+  check: true,
+  lineno: true,
+  row_height: 40,
+  fields: [
+    { name: "name", label: "姓名", uitype: "text", freeze: true, width: 120 },
+    { name: "age", label: "年龄", uitype: "int", width: 80 },
+    { name: "edit", label: "编辑", uitype: "button", icon: "edit", action: { cmd: "edit_user" }, width: 60 }
+  ],
+  miniform: { /* mini form config */ },
+  toolbar: { items: [ /* toolbar buttons */ ] }
+});
+
+container.add_widget(grid);
+```
+
+---
+
+## 调试与日志
+
+使用 `bricks.debug(...)` 输出关键流程日志，例如：
+- 列宽计算结果
+- 滚动事件触发
+- 数据加载过程
+
+可通过浏览器控制台查看。
+
+---
+
+## 依赖说明
+
+本组件依赖以下 `bricks.js` 模块：
+- `bricks.VBox`, `bricks.HBox`：布局容器
+- `bricks.Text`, `bricks.Button`, `bricks.Title1`：基础控件
+- `bricks.MiniForm`, `bricks.Toolbar`：功能控件
+- `bricks.VScrollPanel`：滚动面板
+- `bricks.BufferedDataLoader`：分页数据加载器
+- `bricks.viewFactory`：动态视图工厂
+- `objcopy()`：对象深拷贝工具
+- `convert2int()`：安全转整数
+- `schedule_once()`：延迟执行函数
+
+---
+
+## 设计亮点
+
+✅ **高性能虚拟滚动**  
+通过 `BufferedDataLoader` + `min_threshold/max_threshold` 实现大数据量流畅浏览。
+
+✅ **灵活 UI 扩展性**  
+支持任意 `uitype` 字段类型，可通过 `viewFactory` 扩展。
+
+✅ **双列同步滚动**  
+完美实现冻结列与主体列的垂直同步滚动。
+
+✅ **模块化架构**  
+`Row` 类独立封装行逻辑，易于维护和定制。
+
+---
+
+## 待改进点（建议）
+
+- ❌ 错误：`self.toolbar` 应为 `this.toolbar`
+- 🔧 增加 `destroy()` 方法清理事件监听
+- 📈 支持横向滚动同步（如有必要）
+- 💡 提供 `getValue()` 获取所有选中行数据的方法
+- 🔄 支持列排序、过滤等高级功能扩展
+
+---
+
+## 版本信息
+
+- 编写时间：2025年4月
+- 作者：Bricks Framework 团队
+- 文档版本：v1.0
+
+--- 
+
+> 📘 提示：请确保引入完整 `bricks.js` 框架及其依赖资源（CSS、图标等）以正确渲染组件。
\ No newline at end of file
diff --git a/aidocs/datarow.md b/aidocs/datarow.md
new file mode 100644
index 0000000..1f3e10c
--- /dev/null
+++ b/aidocs/datarow.md
@@ -0,0 +1,311 @@
+# `bricks.DataRow` 技术文档
+
+> **模块**: `bricks.js`  
+> **类名**: `bricks.DataRow`  
+> **继承自**: `bricks.HBox`
+
+---
+
+## 概述
+
+`bricks.DataRow` 是一个用于渲染表格行的 UI 组件，通常用于数据浏览器（Data Browser）或列表视图中。它支持表头行和数据行两种渲染模式，能够根据配置自动构建字段、工具栏，并处理用户交互。
+
+该组件继承自 `bricks.HBox`，因此具备水平布局能力，适用于构建可扩展的数据展示界面。
+
+---
+
+## 配置选项 (Options)
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `toolbar` | Object / null | 工具栏配置对象，包含 `tools` 数组，定义操作图标按钮。在表头中将被替换为空白图标。 |
+| `fields` | Array | 字段定义数组，每个字段描述一个列的显示方式（如名称、类型等）。 |
+| `css` | String / Object | 自定义 CSS 样式，应用于整个 DataRow 容器。 |
+| `browserfields` | Object | 浏览器专用配置：<br>- `exclouded`: 排除显示的字段名数组<br>- `cwidth`: 各字段的列宽映射（单位：字符宽度） |
+| `editexclouded` | Array | （未使用）预留字段排除列表（当前未实现逻辑）。 |
+| `header_css` | String / Object | 表头行的额外 CSS 样式。 |
+| `checkField` | String | 可选字段名，用于启用复选框列（例如选择记录）。值会绑定到 `user_data[checkField]`。 |
+
+### 字段定义 (`fields` 中的对象)
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `name` | String | 字段名，对应数据中的键。 |
+| `label` | String | 列标题；若未提供，则使用 `name` 作为标签。 |
+| `uitype` | String | 控件类型（如 `'str'`, `'int'`, `'date'` 等），决定如何渲染该字段。 |
+| `cwidth` | Number | 列宽（以字符为单位，默认为 10）。优先级低于 `browserfields.cwidth`。 |
+| `value` | Any | （仅用于表头）默认值或标签文本。 |
+| 其他属性 | - | 支持传递给具体 ViewBuilder 的其他参数。 |
+
+---
+
+## 方法
+
+### 构造函数 `constructor(opts)`
+
+初始化 `DataRow` 实例并设置初始状态。
+
+```js
+new bricks.DataRow(options);
+```
+
+#### 参数：
+- `opts` (Object): 配置选项对象，参见上文。
+
+#### 内部初始化：
+- 调用父类构造函数。
+- 初始化 `this.record_w = null` —— 用于存放字段控件的容器。
+
+---
+
+### `render_header()`
+
+渲染表头行（即列标题）。
+
+```js
+row.render_header();
+```
+
+内部调用 `this.render(true)`，指示进入“表头”模式。
+
+---
+
+### `render_data()`
+
+渲染数据行（即实际记录内容）。
+
+```js
+row.render_data();
+```
+
+内部调用 `this.render(false)`，表示渲染真实数据。
+
+---
+
+### `render(header)`
+
+主渲染方法，区分表头与数据行逻辑。
+
+#### 参数：
+- `header` (Boolean)：是否渲染为表头。
+
+#### 行为：
+1. 若存在 `checkField`：
+   - 表头：添加一个空图标（`bricks.BlankIcon`）
+   - 数据行：添加一个可交互的复选框（`bricks.UiCheck`），绑定 `changed` 事件到 `get_check_state`
+2. 调用 `build_fields(header)` 渲染所有字段。
+
+---
+
+### `renew(record)`
+
+更新当前行的数据源并重新渲染字段内容。
+
+#### 参数：
+- `record` (Object): 新的数据记录对象。
+
+#### 行为：
+- 更新 `this.user_data = record`
+- 清空原有字段容器 `record_w`
+- 重建字段控件
+
+> ⚠️ 注意：不会重建整个 DOM 结构，仅刷新字段内容，性能更优。
+
+---
+
+### `get_check_state(e)`
+
+处理复选框状态变化事件。
+
+#### 参数：
+- `e` (Event): 来自 `UiCheck` 的 `changed` 事件。
+
+#### 行为：
+- 获取新值并同步回 `this.user_data[this.checkField]`
+- 触发 `check_changed` 事件，携带自身实例作为参数
+
+```js
+this.dispatch('check_changed', this);
+```
+
+可用于外部监听选中状态变更。
+
+---
+
+### `build_toolbar(header)`
+
+构建工具栏区域（如操作按钮：编辑、删除等）。
+
+#### 参数：
+- `header` (Boolean): 是否为表头模式。
+
+#### 行为：
+- 表头模式下，所有工具替换为占位图标（`blankicon`），保持对齐
+- 数据行模式下，正常加载工具项
+- 创建 `bricks.IconBar` 实例并添加至组件
+- 为每个非空白工具绑定事件监听器，通过 `my_dispatch` 转发事件名
+
+> ✅ 支持事件冒泡机制，便于外部监听工具点击事件。
+
+---
+
+### `my_dispatch(e)`
+
+事件转发函数工厂，生成能正确派发事件的方法。
+
+#### 参数：
+- `e` (String): 事件名称（如 `'edit'`, `'delete'`）
+
+#### 返回：
+- Function: 闭包函数，调用 `this.dispatch(e)`，确保上下文正确。
+
+常用于绑定：
+
+```js
+w.bind(tools[i].name, this.my_dispatch(tools[i].name));
+```
+
+---
+
+### `build_fields(header, cw?)`
+
+创建字段容器并启动字段构建流程。
+
+#### 参数：
+- `header` (Boolean): 是否为表头
+- `cw` (Widget, 可选): 外部传入的容器，默认新建 `HBox`
+
+#### 行为：
+- 创建新的 `HBox` 容器 `record_w`
+- 设置样式类 `childrensize`
+- 添加进主组件
+- 调用 `_build_fields` 执行具体构建
+
+---
+
+### `_build_fields(header, cw)`
+
+私有方法：逐个构建字段控件。
+
+#### 参数：
+- `header` (Boolean): 是否为表头
+- `cw` (Container Widget): 目标容器
+
+#### 流程：
+1. 解析 `browserfields.exclouded` 和 `cwidths` 配置
+2. 将 `checkField` 加入排除列表（避免重复显示）
+3. 遍历 `this.fields`：
+   - 跳过被排除的字段
+   - 构造字段控件参数 `opts`
+     - 表头：显示 `label` 或 `name`
+     - 数据行：从 `user_data` 提取值
+   - 使用 `bricks.get_ViewBuilder(uitype)` 获取对应的视图生成器
+   - 回退到 `'str'` 类型生成器以防不支持的类型
+   - 实例化控件并添加到容器
+   - 添加 CSS 类 `tabular-cell` 保证表格样式一致
+
+---
+
+## 事件系统
+
+`DataRow` 支持以下事件分发：
+
+| 事件名 | 触发时机 | 携带参数 |
+|--------|----------|---------|
+| `check_changed` | 复选框状态改变时 | 当前行实例 (`this`) |
+| `[tool.name]` | 工具栏按钮被点击时（如 `'edit'`, `'delete'`） | 由 `IconBar` 触发，可通过 `bind()` 监听 |
+
+示例监听：
+
+```js
+row.bind('check_changed', function(sender){
+    console.log("选中状态变化:", sender.user_data);
+});
+```
+
+---
+
+## 注册信息
+
+```js
+bricks.Factory.register('DataRow', bricks.DataRow);
+```
+
+允许通过工厂方式创建实例：
+
+```js
+var row = bricks.Factory.create('DataRow', options);
+```
+
+---
+
+## 使用示例
+
+### 创建表头行
+
+```js
+var headerRow = new bricks.DataRow({
+    fields: [
+        { name: 'id', label: 'ID', uitype: 'int', cwidth: 5 },
+        { name: 'name', label: '姓名', uitype: 'str', cwidth: 15 },
+        { name: 'age', label: '年龄', uitype: 'int' }
+    ],
+    checkField: 'selected'
+});
+
+headerRow.render_header(); // 渲染列标题 + 复选框占位
+container.add_widget(headerRow);
+```
+
+### 创建数据行
+
+```js
+var dataRow = new bricks.DataRow({
+    fields: [...],
+    checkField: 'selected',
+    browserfields: {
+        exclouded: ['internal_id'],
+        cwidths: { name: 20 }
+    },
+    toolbar: {
+        tools: [
+            { name: 'edit', icon: 'pencil' },
+            { name: 'delete', icon: 'trash' }
+        ]
+    }
+});
+
+dataRow.renew({ id: 1, name: '张三', age: 25, selected: 1 });
+container.add_widget(dataRow);
+```
+
+---
+
+## 设计特点
+
+- **双模式渲染**：同一组件支持表头与数据行，减少冗余代码。
+- **灵活字段控制**：通过 `browserfields.exclouded` 动态隐藏字段。
+- **列宽管理**：支持全局与字段级 `cwidth` 控制布局。
+- **事件解耦**：通过 `dispatch` 实现松耦合通信。
+- **可扩展性**：基于 `ViewBuilder` 插件机制支持多种字段类型。
+
+---
+
+## 注意事项
+
+1. `editexclouded` 字段目前未在代码中使用，可能是遗留字段。
+2. `toolbar.tools.forEach(...)` 应注意空指针风险，建议增加判空保护。
+3. `_build_fields` 中 `cwidths` 键名为 `cwidths`，但配置写的是 `cwidth`，可能存在拼写错误（应统一为 `cwidth`）。
+4. 建议在 `renew()` 中判断 `record_w` 是否已存在，避免重复创建。
+
+---
+
+## 版本信息
+
+- **Author**: Bricks Framework Team
+- **Version**: 1.0
+- **Last Modified**: 2025-04-05
+
+--- 
+
+✅ 文档完
\ No newline at end of file
diff --git a/aidocs/dataviewer.md b/aidocs/dataviewer.md
new file mode 100644
index 0000000..30ccf98
--- /dev/null
+++ b/aidocs/dataviewer.md
@@ -0,0 +1,502 @@
+# `bricks.DataViewer` 技术文档
+
+> **版本：1.0**  
+> **继承自：`bricks.VBox`**  
+> **用途：通用数据展示组件，支持分页加载、滚动加载、工具栏操作与动态表单交互**
+
+---
+
+## 概述
+
+`bricks.DataViewer` 是一个可扩展的数据视图组件，用于在 Web 界面中以可视化方式展示和管理结构化数据。它基于 `bricks.VBox` 容器构建，具备以下核心功能：
+
+- 支持异步分页加载远程数据（通过 `PageDataLoader`）
+- 垂直滚动区域自动加载上一页/下一页
+- 可配置的工具栏（支持增删改查等操作）
+- 行选择与事件通知机制
+- 内置编辑表单弹窗（新增、更新、克隆、删除）
+- 高度可定制化（可通过子类重写关键方法实现自定义渲染）
+
+该组件通常作为列表、表格或卡片式数据展示的基础容器使用。
+
+---
+
+## 组件结构
+
+```js
+var bricks = window.bricks || {};
+bricks.DataViewer = class extends bricks.VBox { ... }
+```
+
+### 注册名称
+```js
+bricks.Factory.register('DataViewer', bricks.DataViewer);
+```
+可通过工厂创建：
+```js
+let viewer = bricks.Factory.build('DataViewer', opts);
+```
+
+---
+
+## 构造函数
+
+```js
+constructor(opts)
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `opts.data_url` | String | 是 | 数据请求 URL |
+| `opts.data_params` | Object | 否 | 请求附加参数 |
+| `opts.page_rows` | Number | 否 | 每页行数，默认由 `PageDataLoader` 控制 |
+| `opts.data_method` | String | 否 | HTTP 方法（如 `'GET'`, `'POST'`），默认 `'GET'` |
+| `opts.cache_limit` | Number | 否 | 缓存页面数量限制 |
+| `opts.editable` | Object | 否 | 编辑配置对象（见下文） |
+| `opts.toolbar` | Object | 否 | 工具栏自定义项 |
+| `opts.row_options` | Object | 否 | 行级选项（字段、排除字段等） |
+
+### 初始化行为
+
+1. 设置默认布局样式：
+   - 宽高为 `100%`
+   - 溢出隐藏（`overflow: hidden`）
+2. 创建 `PageDataLoader` 实例用于数据加载
+3. 初始化状态变量（选中行、加载锁、偏移量等）
+4. 绑定事件：`row_check_changed`
+5. 延迟调用 `build_all()` 进行 UI 构建
+
+---
+
+## 核心属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `loader` | `PageDataLoader` | 负责数据分页加载 |
+| `scrollpanel` | `VScrollPanel` | 主内容滚动容器 |
+| `filler_widget` | `Filler` | 占位容器，容纳 `scrollpanel` |
+| `toolbar_w` | `IconTextBar` | 工具栏组件 |
+| `select_row` | Widget | 当前选中的记录行 widget |
+| `active_item` | Widget | 当前激活项目（保留字段） |
+| `loading` | Boolean | 是否正在加载数据 |
+| `data_offset` | Number | 数据起始偏移位置（用于反向插入） |
+| `old_params` | Object | 上次请求参数，防止重复加载 |
+| `key_select_items` | Array | 支持键盘导航的选择项集合 |
+| `check_changed_row` | Object | 最近一次变更的行数据 |
+| `keyselectable` | Boolean | 是否允许键盘选择 |
+
+---
+
+## 生命周期方法
+
+### `async build_all()`
+
+主 UI 构建入口，按顺序执行以下步骤：
+
+```js
+await this.build_other();
+this.scrollpanel.bind('min_threshold', this.load_previous_page.bind(this));
+this.scrollpanel.bind('max_threshold', this.load_next_page.bind(this));
+await this.render();
+this.set_key_select_items();
+```
+
+#### 子构建方法：
+| 方法 | 功能 |
+|------|------|
+| `build_title_widget()` | （预留）构建标题区 |
+| `build_description_widget()` | （预留）构建描述区 |
+| `build_toolbar_widget()` | 构建顶部工具栏 |
+| `build_records_area()` | 创建滚动面板用于显示数据行 |
+| `build_other()` | 子类可扩展的额外构建逻辑（空实现） |
+
+---
+
+### `async render(params)`
+
+重新加载并渲染数据。
+
+#### 参数
+- `params`: 请求参数（合并到原始 `data_params`）
+
+#### 流程
+1. 若参数未变化 → 返回
+2. 使用 `loader.loadData(params)` 获取数据
+3. 清空当前内容
+4. 执行前置处理 `before_data_handle()`
+5. 处理数据 `dataHandle(d)`
+
+> ⚠️ 自动去重：若 `params === old_params` 则跳过。
+
+---
+
+### `async before_data_handle()`
+
+钩子函数，在数据处理前调用。可用于预处理或状态清理。
+
+> 默认为空，供子类覆盖。
+
+---
+
+### `async dataHandle(d)`
+
+处理从 `loader` 返回的数据对象。
+
+#### 输入格式示例
+```json
+{
+  "rows": [...],
+  "add_page": 1,
+  "delete_page": 2
+}
+```
+
+#### 行为
+- 调用 `renderPageData(rows, add_page)`
+- 如果有 `delete_page`，调用 `delete_page(page_num)` 删除旧页
+
+---
+
+## 数据渲染相关
+
+### `build_records_area()`
+
+创建主数据显示区域：
+
+```js
+this.filler_widget = new bricks.Filler({});
+this.add_widget(this.filler_widget);
+this.scrollpanel = new bricks.VScrollPanel({});
+this.filler_widget.add_widget(this.scrollpanel);
+```
+
+> 使用 `Filler + VScrollPanel` 结构确保布局适应。
+
+---
+
+### `async renderPageData(data, page)`
+
+将一批数据渲染成可视行。
+
+#### 参数
+- `data`: 数组，每项是一个数据记录
+- `page`: 页面编号
+
+#### 特殊逻辑
+- 如果不是最大页（历史页）：数据逆序，并从前部插入（维护时间顺序）
+- 否则：正常追加至末尾
+
+内部循环调用 `build_row()`。
+
+---
+
+### `async build_record_view(record)`
+
+**抽象方法**：生成单条记录的 UI 组件。
+
+#### 默认实现
+```js
+var w = new bricks.VBox({width: '100px', height:'100px'});
+w.set_css('test_box');
+return w;
+```
+
+> ✅ 必须由子类重写以实现具体展示样式（如表格行、卡片等）
+
+---
+
+### `async build_row(record, page, pos)`
+
+将一条记录添加到 `scrollpanel` 中。
+
+#### 参数
+- `record`: 数据对象
+- `page`: 所属页码
+- `pos`: 插入位置（null 表示末尾）
+
+#### 步骤
+1. 调用 `build_record_view(record)` 创建 widget
+2. 设置属性 `data-page` 便于后续删除
+3. 添加到 `scrollpanel` 指定位置
+
+---
+
+## 工具栏与用户交互
+
+### `build_toolbar_widget()`
+
+根据配置生成工具栏按钮。
+
+#### 支持的操作（当 `editable` 存在时）
+| 名称 | 图标 | 条件 | 提示 |
+|------|------|------|------|
+| `add` | `add_icon` 或默认图标 | 总是显示 | 新增记录 |
+| `update` | `update_icon` | 需选中行 | 更新选中项 |
+| `clone` | `clone_icon` | 需选中行 | 克隆选中项 |
+| `delete` | `delete_icon` | 需选中行 | 删除选中项 |
+
+> 图标路径通过 `bricks_resource()` 解析 SVG 资源。
+
+此外，支持合并外部传入的 `toolbar.tools`。
+
+最终创建 `IconTextBar` 并绑定命令事件。
+
+---
+
+### `command_event_handle(event)`
+
+处理工具栏点击事件。
+
+#### 分发逻辑
+| 命令名 | 行为 |
+|--------|------|
+| `add` | 调用 `add_record()` |
+| `update` | 调用 `update_record(select_row)` |
+| `clone` | 调用 `clone_record(select_row)` |
+| `delete` | 调用 `delete_record(select_row)` |
+| 其他 | 触发全局事件 `dispatch(name, data)` |
+
+> 若操作需要选中行但无选中项，则提示错误。
+
+---
+
+## 编辑功能
+
+### 字段控制
+
+#### `get_edit_fields()`
+提取可编辑字段，过滤掉 `editexclouded` 中指定的字段。
+
+> 结果保存在 `this.fields` 数组中。
+
+#### `get_hidefields()`
+获取应隐藏提交的字段（来自 `data_params`），转换为 `{name, value, uitype: 'hide'}` 形式。
+
+---
+
+### 表单构建
+
+| 方法 | 功能 |
+|------|------|
+| `build_add_form()` | 构建“新增”表单 |
+| `build_update_form(data)` | 构建“更新”表单（带 id 隐藏域） |
+| `build_clone_form(data)` | 构建“克隆”表单（不包含 id） |
+
+所有表单均基于 `bricks.Form`，并注入隐藏字段和编辑字段。
+
+---
+
+### 弹窗管理
+
+#### `build_window(icon, title, form)`
+创建通用弹窗（`PopupWindow`）封装表单。
+
+##### 配置
+- 居中定位 (`archor: "cc"`)
+- 可移动、可缩放
+- 尺寸：宽 90%，高 70%
+- 绑定表单的 `cancel` 事件关闭窗口
+
+---
+
+### 编辑流程
+
+#### `add_record()`
+1. 创建新增表单
+2. 弹出窗口
+3. 监听 `submited` 事件 → 调用 `add_record_finish(win, event)`
+
+#### `add_record_finish(f, event)`
+1. 关闭窗口
+2. 重新加载数据
+3. 解析响应 JSON 并构建反馈组件（如消息提示）
+
+#### `update_record()`
+1. 获取当前选中行数据
+2. 创建更新表单（含 `id` 隐藏域）
+3. 弹窗并监听 `submited` → `update_record_finish()`
+
+#### `update_record_finish(win, form, event)`
+1. 调用 `renew_record_view(form, row)` 更新本地视图
+2. 显示服务器返回结果组件
+3. 关闭窗口
+
+#### `clone_record()`
+同 `add_record`，但初始值为原记录数据
+
+#### `delete_record(row, record)`
+弹出确认对话框（`Conform`），确认后调用 `delete_record_act()`
+
+#### `delete_record_act()`
+1. 发送 DELETE 请求（POST with body）
+2. 接收响应并构建反馈组件
+3. 若成功（返回 Message 类型），移除对应行并刷新
+
+---
+
+## 滚动加载机制
+
+### `load_previous_page()`
+
+加载前一页数据（向上滚动触底）
+
+#### 流程
+1. 检查是否已在加载 → 防抖
+2. 显示 loading 指示器（`Running`）
+3. 调用 `loader.loadPreviousPage()`
+4. 成功则调用 `dataHandle(d)`
+5. 恢复滚动位置（按 `pos_rate`）
+6. 隐藏 loading
+
+> 错误被捕获并打印 debug 日志。
+
+---
+
+### `load_next_page()`
+
+加载下一页数据（向下滚动触底）
+
+逻辑类似 `load_previous_page()`，但无需调整滚动位置。
+
+---
+
+## 辅助方法
+
+### `set_key_select_items()`
+设置支持键盘导航的元素集合（除去第一个 filler widget）。
+
+用于后续方向键选择。
+
+---
+
+### `delete_page(page)`
+批量删除属于某一页的所有 DOM 元素。
+
+通过 `[data-page="X"]` 查询 selector 获取 widgets 并逐个移除。
+
+---
+
+### `record_check_changed(event)`
+处理行内复选框变更事件。
+
+转发事件为 `row_check_changed`，携带 `user_data`。
+
+---
+
+### `renew_record_view(form, row)`
+用表单最新值更新某行的 `user_data`。
+
+```js
+row.user_data = { ...row.user_data, ...form._getValue() };
+row.renew(data); // 视图刷新
+```
+
+> `renew()` 是 widget 的生命周期方法，需子类实现。
+
+---
+
+## 事件系统
+
+| 事件名 | 触发时机 | 参数 |
+|-------|---------|------|
+| `row_check_changed` | 行内复选框改变 | `{user_data}` |
+| `command` | 工具栏按钮点击 | `{name, selected_row}` |
+| `submited` | 表单提交成功 | `{params: Response}` |
+| `conformed` / `discard` | 删除确认框选择 | —— |
+
+---
+
+## 设计原则与扩展建议
+
+### 可扩展点（推荐子类覆盖）
+
+| 方法 | 用途 |
+|------|------|
+| `build_other()` | 添加自定义组件 |
+| `build_title_widget()` | 自定义标题 |
+| `build_record_view(record)` | 自定义行渲染模板 |
+| `before_data_handle()` | 数据加载前准备 |
+| `renew(record)` in row widget | 行内容更新逻辑 |
+
+---
+
+### 性能优化特性
+
+- 数据缓存与懒加载
+- 滚动阈值触发分页
+- 请求去重（参数比对）
+- 页面级删除释放内存
+
+---
+
+## 使用示例（伪代码）
+
+```js
+let viewer = new bricks.DataViewer({
+  data_url: '/api/users',
+  data_params: { dept_id: 101 },
+  page_rows: 20,
+  editable: {
+    add_icon: 'imgs/user_add.svg',
+    new_data_url: '/api/users/create',
+    update_data_url: '/api/users/update',
+    delete_data_url: '/api/users/delete'
+  },
+  row_options: {
+    fields: [
+      { name: 'name', label: '姓名', uitype: 'text' },
+      { name: 'age', label: '年龄', uitype: 'number' }
+    ],
+    editexclouded: ['created_at']
+  }
+});
+
+// 自定义行渲染
+viewer.build_record_view = function(record) {
+  let w = new bricks.HBox({ width: '100%', padding: 10 });
+  w.add_widget(new bricks.Label({ text: record.name }));
+  w.add_widget(new bricks.Label({ text: record.age }));
+  w.user_data = record;
+  return w;
+};
+```
+
+---
+
+## 调试信息
+
+- `bricks.debug_obj = this.scrollpanel;` —— 方便调试滚动容器
+- 所有关键操作均有 `bricks.debug()` 输出
+- 支持 `bricks.show_error()` 提示用户错误
+
+---
+
+## 依赖组件
+
+| 组件 | 作用 |
+|------|------|
+| `bricks.VBox` | 布局基类 |
+| `bricks.VScrollPanel` | 滚动容器 |
+| `bricks.PageDataLoader` | 分页数据加载器 |
+| `bricks.IconTextBar` | 工具栏 |
+| `bricks.Form` | 表单引擎 |
+| `bricks.PopupWindow` | 弹窗容器 |
+| `bricks.Conform` | 确认对话框 |
+| `bricks.Running` | 加载指示器 |
+| `bricks.HttpJson` | JSON 请求客户端 |
+| `bricks.widgetBuild` | 动态组件构建 |
+
+---
+
+## 版本历史
+
+| 版本 | 修改内容 |
+|------|----------|
+| 1.0 | 初始公开文档版本 |
+
+---
+
+> 📝 文档生成时间：2025-04-05  
+> © 2025 Bricks Framework Team
\ No newline at end of file
diff --git a/aidocs/docxviewer.md b/aidocs/docxviewer.md
new file mode 100644
index 0000000..7bfa25b
--- /dev/null
+++ b/aidocs/docxviewer.md
@@ -0,0 +1,262 @@
+# Bricks 文档查看器组件技术文档
+
+本技术文档介绍了基于 `bricks.js` 框架的三种文档文件在线预览组件：`DOCXviewer`、`EXCELviewer` 和 `PDFviewer`。这些组件支持通过 URL 加载并渲染 `.docx`、`.xlsx/.xls` 和 `.pdf` 文件，适用于网页端轻量级文档展示场景。
+
+---
+
+## 🔧 依赖说明
+
+以下第三方库必须在页面中提前加载：
+
+```html
+<!-- 必需：Mammoth.js - 用于 DOCX 转 HTML -->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/mammoth/1.4.2/mammoth.browser.min.js"></script>
+
+<!-- 必需：SheetJS (xlsx) - 用于 Excel 解析 -->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/xlsx/0.18.5/xlsx.full.min.js"></script>
+
+<!-- 必需：PDF.js - 用于 PDF 渲染 -->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.4.120/pdf.min.js"></script>
+```
+
+> ⚠️ 注意：确保 `pdfjsLib` 已全局可用（通常由 PDF.js 提供）。
+
+---
+
+## 📦 组件概览
+
+| 组件名         | 功能描述                     | 支持格式     |
+|----------------|------------------------------|--------------|
+| `DOCXviewer`   | 预览 Word 文档 (.docx)       | `.docx`      |
+| `EXCELviewer`  | 预览 Excel 表格文件          | `.xlsx`, `.xls` |
+| `PDFviewer`    | 预览 PDF 文档                | `.pdf`       |
+
+所有组件均继承自 `bricks.VBox`，可通过 `bricks.Factory.register()` 注册使用。
+
+---
+
+## 1. ✅ DOCXviewer
+
+将 `.docx` 文件转换为 HTML 并嵌入页面显示。
+
+### 类定义
+```javascript
+bricks.DOCXviewer = class extends bricks.VBox
+```
+
+### 构造函数
+```javascript
+constructor(opts)
+```
+
+#### 参数
+- `opts` `{Object}`: 配置选项对象。
+  - `url` `{String}`: 指向 `.docx` 文件的远程或本地 URL。
+
+#### 示例
+```javascript
+const docViewer = new bricks.DOCXviewer({
+  url: 'https://example.com/document.docx'
+});
+```
+
+### 方法
+
+#### `async set_url(url)`
+从指定 URL 获取 `.docx` 文件，并使用 Mammoth.js 转换为 HTML 显示。
+
+##### 流程
+1. 使用 `HttpArrayBuffer` 异步获取文件二进制数据。
+2. 调用 `mammoth.convertToHtml()` 将 ArrayBuffer 转为 HTML 字符串。
+3. 插入到组件 DOM 容器内。
+
+##### 参数
+- `url` `{String}`: 可选，若未传则使用实例的 `this.url`。
+
+---
+
+## 2. ✅ EXCELviewer
+
+支持多工作表 Excel 文件的交互式浏览。
+
+### 类定义
+```javascript
+bricks.EXCELviewer = class extends bricks.VBox
+```
+
+### 构造函数
+```javascript
+constructor(opts)
+```
+
+#### 参数
+- `opts` `{Object}`:
+  - `url` `{String}`: Excel 文件地址。
+  - （自动设置）`height: "100%"`
+
+#### UI 结构
+- 上部：横向滚动条式工作表标签栏 (`HBox`)
+- 下部：内容区域 (`Filler`) 显示当前选中的 sheet
+
+#### 示例
+```javascript
+const excelViewer = new bricks.EXCELviewer({
+  url: 'https://example.com/data.xlsx'
+});
+```
+
+### 方法
+
+#### `async set_url(url)`
+加载 Excel 文件并解析所有工作表名称，生成可点击标签。
+
+##### 步骤
+1. 获取文件 ArrayBuffer。
+2. 使用 `XLSX.read(data, {type: 'array'})` 解析 workbook。
+3. 遍历 `SheetNames` 创建文本按钮，绑定点击事件。
+
+#### `show_sheet_by_name(sheetname, widget)`
+切换显示指定工作表的内容。
+
+##### 功能
+- 更新选中状态样式（添加 `selected` CSS 类）
+- 使用 `XLSX.utils.sheet_to_html()` 生成表格 HTML
+- 嵌入 `VScrollPanel` 实现垂直滚动
+- 替换内容容器中的子组件
+
+##### 内部变量
+- `this.cur_sheetname`: 当前显示的工作表名
+- `this.workbook`: 缓存 workbook 对象以供后续访问
+
+---
+
+## 3. ✅ PDFviewer
+
+逐页渲染 PDF 文件为 Canvas 图像。
+
+### 类定义
+```javascript
+bricks.PDFviewer = class extends bricks.VBox
+```
+
+### 构造函数
+```javascript
+constructor(opts)
+```
+
+#### 参数
+- `opts` `{Object}`:
+  - `url` `{String}`: PDF 文件路径
+  - （自动设置）`width: '100%'`
+
+#### 示例
+```javascript
+const pdfViewer = new bricks.PDFviewer({
+  url: 'https://example.com/report.pdf'
+});
+```
+
+### 方法
+
+#### `async set_url(url)`
+加载 PDF 并启动渲染流程。
+
+##### 步骤
+1. 使用 `HttpArrayBuffer` 获取二进制数据。
+2. 调用 `pdfjsLib.getDocument({ data: ab })` 初始化文档。
+3. 遍历每一页，调用 `getPage(i)` 并异步渲染。
+
+#### `add_page_content(page)`
+将单个 PDF 页面渲染为 `<canvas>` 元素并插入组件。
+
+##### 渲染参数
+- 缩放比例：`scale = 1.5`
+- 使用 `page.getViewport()` 计算视口尺寸
+- 创建 canvas，设置宽高，调用 `page.render()` 绘制
+
+##### UI 布局
+- 每页后插入一个 `Splitter` 分隔符（逻辑待修复）
+- 使用 `JsWidget` 包裹 canvas 实现集成
+
+> ❗注意：原代码中 `i < this.pdf.numPages` 的 `i` 未定义，应改为索引判断或移除条件。
+
+##### 修复建议：
+```js
+// 修改 add_page_content 中的判断逻辑
+if (page.pageNumber < this.pdf.numPages) {
+  const splitter = new bricks.Splitter();
+  this.add_widget(splitter);
+}
+```
+
+---
+
+## 🔗 工具函数
+
+### `extractBodyContent(htmlString)`
+提取 HTML 字符串中 `<body>...</body>` 标签之间的内容。
+
+#### 参数
+- `htmlString` `{String}`: 完整 HTML 字符串
+
+#### 返回值
+- `{String|null}`: 匹配到的 body 内容，否则返回 `null`
+
+#### 正则表达式
+```js
+/<body[^>]*>([\s\S]*?)<\/body>/i
+```
+
+> 💡 当前代码中该函数被注释掉，可用于清理 XLSX 输出中的多余头尾信息。
+
+---
+
+## 🧱 组件注册
+
+最后，三个组件通过 `bricks.Factory` 注册，可在模板或动态创建时使用字符串标识符：
+
+```javascript
+bricks.Factory.register('DOCXviewer', bricks.DOCXviewer);
+bricks.Factory.register('EXCELviewer', bricks.EXCELviewer);
+bricks.Factory.register('PDFviewer', bricks.PDFviewer);
+```
+
+### 使用示例（工厂模式）
+```javascript
+const viewer = bricks.Factory.create('PDFviewer', {
+  url: 'manual.pdf'
+});
+parentContainer.add_widget(viewer);
+```
+
+---
+
+## 🛠️ 已知问题与改进建议
+
+| 问题 | 描述 | 建议 |
+|------|------|-------|
+| `i` 未定义 | `add_page_content` 中 `i < numPages` 报错 | 改用 `page.pageNumber` 判断 |
+| 性能问题 | 多页 PDF 同时请求可能导致卡顿 | 添加顺序加载或懒加载机制 |
+| 样式控制弱 | 输出 HTML 缺乏定制化样式 | 提供 `customStyle` 回调或封装容器类 |
+| 错误处理不足 | `pdfjsLib` catch 仅打印日志 | 提供错误 UI 反馈机制 |
+
+---
+
+## 📎 总结
+
+这三个组件构成了一个轻量级、模块化的文档预览系统，适合集成于 Web 应用前端，实现无需下载即可查看常见办公文档的功能。
+
+### 特性亮点
+- 基于标准浏览器 API 与流行解析库
+- 支持异步加载和动态渲染
+- 组件化设计，易于扩展和复用
+- 与 `bricks.js` UI 框架无缝集成
+
+### 推荐用途
+- 在线帮助手册预览
+- 后台管理系统文档查看
+- 教学平台课件展示
+
+---
+
+> 📚 **提示**：请确保服务器允许跨域访问文档资源（CORS），否则 `HttpArrayBuffer.get()` 请求将失败。
\ No newline at end of file
diff --git a/aidocs/dynamicaccordion.md b/aidocs/dynamicaccordion.md
new file mode 100644
index 0000000..673774b
--- /dev/null
+++ b/aidocs/dynamicaccordion.md
@@ -0,0 +1,399 @@
+# `DynamicAccordion` 技术文档
+
+> **模块名称：** `bricks.DynamicAccordion`  
+> **继承自：** `bricks.VScrollPanel`  
+> **用途：** 动态可折叠列表组件，支持分页加载、内容动态渲染、编辑操作（增删改）、工具栏扩展等高级功能。
+
+---
+
+## 目录
+
+- [1. 概述](#1-概述)
+- [2. 核心类结构](#2-核心类结构)
+  - [2.1 `bricks.AccordionItem`](#21-bricksaccordionitem)
+  - [2.2 `bricks.AccordionInfo`](#22-bricksaccordioninfo)
+  - [2.3 `bricks.DynamicAccordion`](#23-bricksdynamicaccordion)
+- [3. 配置选项 (`opts`)](#3-配置选项-opts)
+- [4. 生命周期与构建流程](#4-生命周期与构建流程)
+- [5. 主要方法说明](#5-主要方法说明)
+  - [5.1 渲染控制](#51-渲染控制)
+  - [5.2 内容生成](#52-内容生成)
+  - [5.3 数据处理与分页](#53-数据处理与分页)
+  - [5.4 编辑功能](#54-编辑功能)
+  - [5.5 事件系统](#55-事件系统)
+- [6. CSS 类名约定](#6-css-类名约定)
+- [7. 使用示例](#7-使用示例)
+- [8. 注意事项](#8-注意事项)
+
+---
+
+## 1. 概述
+
+`bricks.DynamicAccordion` 是一个基于 `VScrollPanel` 的高级可折叠面板组件，用于展示大量条目数据。每个条目由标题区域和可展开的内容区组成，支持：
+
+- 分页异步加载数据
+- 可配置的记录视图模板（`record_view`）
+- 展开后动态加载详细内容（`content_view`）
+- 行内工具栏（支持自定义按钮及编辑操作）
+- 增删改查（CRUD）交互支持
+- 条件性内容显示（依赖字段值）
+
+适用于需要高效展示并操作大量结构化数据的场景，如后台管理界面中的日志、订单、用户列表等。
+
+---
+
+## 2. 核心类结构
+
+### 2.1 `bricks.AccordionItem`
+
+```js
+class extends bricks.VBox
+```
+
+表示单个可折叠项的容器，包含两个子部件：
+- `AccordionInfo`：点击触发展开/收起的头部
+- `VBox`：隐藏的内容区域（默认不显示）
+
+#### 构造函数
+```js
+constructor(opts) {
+  super(opts);
+  this.set_css('accordion-item');
+}
+```
+
+#### 特性
+- 自动添加 CSS 类 `accordion-item`
+- 继承 `VBox` 布局特性（垂直排列）
+
+---
+
+### 2.2 `bricks.AccordionInfo`
+
+```js
+class extends bricks.FHBox
+```
+
+代表折叠项的标题部分，通常用于显示摘要信息，并绑定点击事件以切换内容可见性。
+
+#### 构造函数
+```js
+constructor(opts) {
+  super(opts);
+  this.set_css('accordion-item-info');
+}
+```
+
+#### 特性
+- 使用 `FHBox` 实现水平布局
+- 添加 CSS 类 `accordion-item-info`
+- 存储关联的数据记录在 `user_data` 属性中
+
+---
+
+### 2.3 `bricks.DynamicAccordion`
+
+主控件类，负责整体逻辑调度、数据加载、UI 构建与交互响应。
+
+```js
+class extends bricks.VScrollPanel
+```
+
+#### 注册方式
+```js
+bricks.Factory.register('DynamicAccordion', bricks.DynamicAccordion);
+```
+
+允许通过工厂方法创建实例：
+```js
+bricks.createWidget("DynamicAccordion", {...});
+```
+
+---
+
+## 3. 配置选项 (`opts`)
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `data_url` | String | 获取数据的 API 地址 |
+| `data_method` | String (可选) | 请求方法，默认为 `'GET'` |
+| `data_params` | Object (可选) | 发送请求时附加的参数 |
+| `cache_limit` | Number (可选) | 缓存页数上限 |
+| `page_rows` | Number (可选) | 每页返回的行数 |
+| `row_cheight` | Number (可选, 默认: `1.5`) | 每行高度倍率（影响布局计算） |
+| `record_view` | Widget 描述对象 | 定义每行摘要区域的 UI 结构 |
+| `content_rely_on` | String (可选) | 控制是否展开内容的字段名 |
+| `content_rely_value` | Any (可选) | 上述字段应匹配的值才能展开内容 |
+| `editable` | Object (可选) | 启用编辑模式的相关配置 |
+| &nbsp;&nbsp;`.add_icon`, `.update_icon`, `.delete_icon` | String | 图标路径或资源引用 |
+| &nbsp;&nbsp;`.form_cheight` | Number | 表单高度系数 |
+| &nbsp;&nbsp;`.new_data_url`, `.update_data_url`, `.delete_data_url` | String | 对应操作的提交 URL |
+| `fields` | Array\<Field\> | 字段定义数组，用于表单和列头渲染 |
+| `record_toolbar` | Object (可选) | 自定义行工具栏按钮配置 |
+| `record_toolbar_collapsable` | Boolean (可选) | 工具栏是否可折叠（未完全实现） |
+| `header` | Object (可选) | 头部固定行配置（暂未启用） |
+| `content_view` | Widget 描述对象 | 展开后显示的详情内容模板 |
+| `title` | String (可选) | 页面标题文本（i18n 支持） |
+| `description` | String (可选) | 页面描述文本 |
+
+> ⚠️ 所有字符串文本均支持国际化（`i18n: true`）。
+
+---
+
+## 4. 生命周期与构建流程
+
+`build_all()` 方法是初始化入口，在构造完成后延迟执行（`schedule_once(..., 0.1)`）：
+
+```js
+async build_all() {
+  if (this.title)        this.build_title();
+  if (this.description)  this.build_description();
+  await this.build_toolbar();
+  await this.build_header();
+
+  this.container = new bricks.VScrollPanel({});
+  this.add_widget(new bricks.Filler().add_widget(this.container));
+
+  this.container.bind('min_threshold', this.load_previous_page.bind(this));
+  this.container.bind('max_threshold', this.load_next_page.bind(this));
+
+  await this.render();
+}
+```
+
+### 流程图解：
+```
+[初始化] 
+   ↓
+build_title() → 添加标题
+build_description() → 添加描述
+build_toolbar() → 添加全局工具栏
+build_header() → 创建表头（模拟）
+   ↓
+创建内部容器 container (VScrollPanel)
+   ↓
+绑定滚动触底/触顶事件 → 分页加载
+   ↓
+render() → 加载并渲染第一页数据
+```
+
+---
+
+## 5. 主要方法说明
+
+### 5.1 渲染控制
+
+#### `render(params)`
+根据参数重新加载数据并刷新 UI。
+
+- 若参数未变，则跳过
+- 调用 `loader.loadData(params)` 获取数据
+- 成功后调用 `dataHandle(d)`
+
+#### `dataHandle(d)`
+处理服务器返回的数据包：
+```js
+{
+  rows: [...],       // 当前页数据
+  add_page: 2,       // 新增页码
+  delete_page: 1     // 应删除的旧页码（超出缓存限制）
+}
+```
+
+调用 `renderAccordionItems(data, page)` 渲染新项，并清理过期页。
+
+---
+
+### 5.2 内容生成
+
+#### `build_item(record)`
+构建单个可折叠项：
+- 创建 `AccordionItem`
+- 调用 `build_info(item, record)` 构建标题区
+- 创建隐藏的 `content` 区域
+- 绑定点击事件：`line_clicked(info, content, record)`
+- 返回完整 `item`
+
+若 `record === null`，则作为“表头”使用。
+
+#### `build_info(item, record)`
+生成标题区域 UI：
+- 使用 `widgetBuild(this.record_view, info, record)` 渲染摘要内容
+- 插入 `record_toolbar`（含编辑图标）
+- 设置 `info.user_data = record`
+- 返回 `AccordionInfo` 实例
+
+当无 `record` 时，用于生成列头标签。
+
+---
+
+### 5.3 数据处理与分页
+
+#### `load_previous_page() / load_next_page()`
+滚动接近边界时自动加载前后页：
+- 显示加载动画（`Running` 提示）
+- 设置 `this.loading = true` 防止重复请求
+- 调用 `loader.loadPreviousPage()` 或 `loadNextPage()`
+- 成功后调用 `dataHandle()` 并恢复滚动位置
+- 错误捕获并输出调试日志
+
+#### `delete_page(page)`
+移除指定页的所有 DOM 元素：
+```js
+querySelectorAll('[data-page="X"]')
+→ 移除对应 widget
+```
+
+确保内存和 DOM 不泄漏。
+
+---
+
+### 5.4 编辑功能
+
+#### 新增记录
+- `add_record(info)`：打开内嵌表单
+- `add_record_abort()`：取消新增
+- `add_record_finish()`：提交成功后刷新列表
+
+#### 更新记录
+- `update_record(info, record)`：弹出编辑表单
+- `update_cancel()`：取消编辑
+- `update_record_finish()`：保存后更新视图或提示
+
+#### 删除记录
+- `delete_record(info, record)`：弹出确认框
+- `delete_record_act()`：发送删除请求，删除成功则移除该项
+
+#### 新建表单快捷入口
+- `build_new_form()`：顶部添加“+”按钮和隐藏表单
+- 点击按钮展开/收起新建表单
+- 提交后自动调用 `render()` 刷新列表
+
+---
+
+### 5.5 事件系统
+
+#### 内部事件绑定
+- `info.bind('click', line_clicked)`：行点击展开内容
+- `IconBar` 工具按钮绑定各种事件（`add`, `update`, `delete`）
+- 自定义工具按钮通过 `fire_event(name, data)` 派发事件
+
+#### 外部可监听事件
+| 事件名 | 触发时机 | 参数 |
+|--------|----------|------|
+| `row_selected` | 用户点击某一行 | `info` widget |
+| `conformed` | 删除确认后 | —— |
+| `submited` | 表单提交成功 | 响应对象 |
+| `[custom_tool_name]` | 自定义工具按钮被点击 | `record` 数据 |
+
+可通过 `bind(event, handler)` 监听。
+
+---
+
+## 6. CSS 类名约定
+
+| 类名 | 作用 |
+|------|------|
+| `.accordion-item` | 整个折叠项外层容器 |
+| `.accordion-item-info` | 折叠项标题区域 |
+| `.accordion-item-info-selected` | 当前行被选中状态 |
+| `.accordion-item-content` | 内容区域样式基类 |
+| `.filler` | 占位填充容器（用于自适应高度） |
+
+建议配合 SCSS 定义主题风格，例如圆角、阴影、过渡动画等。
+
+---
+
+## 7. 使用示例
+
+```js
+var accordion = new bricks.DynamicAccordion({
+  title: "User List",
+  description: "Manage all registered users.",
+  data_url: "/api/users",
+  page_rows: 10,
+  cache_limit: 5,
+
+  fields: [
+    { name: "name", label: "Name" },
+    { name: "email", label: "Email" },
+    { name: "status", label: "Status" }
+  ],
+
+  record_view: {
+    widgettype: "HBox",
+    options: { cheight: 1.5 },
+    subwidgets: [
+      { widgettype: "Text", options: { otext: "{{name}}" } },
+      { widgettype: "Text", options: { otext: "{{email}}", halign: "right" } }
+    ]
+  },
+
+  content_view: {
+    widgettype: "Form",
+    options: {
+      fields: [
+        { name: "name", uitype: "text" },
+        { name: "email", uitype: "email" },
+        { name: "bio", uitype: "textarea" }
+      ]
+    }
+  },
+
+  editable: {
+    form_cheight: 8,
+    new_data_url: "/api/users/create",
+    update_data_url: "/api/users/update",
+    delete_data_url: "/api/users/delete",
+    add_icon: "/static/icons/add.svg"
+  },
+
+  record_toolbar: {
+    tools: [
+      { name: "view_logs", tip: "View operation logs", icon: "/icons/logs.svg" }
+    ]
+  }
+});
+
+// 监听自定义操作
+accordion.bind("view_logs", function(record){
+  console.log("查看日志:", record);
+});
+```
+
+---
+
+## 8. 注意事项
+
+1. **性能优化**
+   - 支持分页缓存，避免一次性加载过多数据
+   - 滚动加载机制减少初始等待时间
+   - `cache_limit` 应合理设置以防内存占用过高
+
+2. **内容懒加载**
+   - `content_view` 仅在点击展开时构建，节省资源
+   - 再次点击会清除内容（`clear_widgets()`），防止状态残留
+
+3. **国际化支持**
+   - 所有文本建议使用 `otext` + `i18n: true` 配合语言包
+
+4. **DOM 清理**
+   - 删除页面时主动移除 widgets 和事件监听（依赖框架 GC）
+
+5. **扩展性**
+   - 可通过 `record_toolbar` 添加自定义操作按钮
+   - `fire_event()` 支持插件式开发
+
+6. **兼容性**
+   - 依赖 `bricks.PageDataLoader`, `bricks.HttpJson`, `bricks.widgetBuild` 等基础模块
+   - 需确保这些模块已正确加载
+
+---
+
+✅ **推荐搭配组件：**
+- `bricks.Form`：用于编辑表单
+- `bricks.Conform`：删除确认对话框
+- `bricks.Running`：加载指示器
+- `bricks.IconBar`：工具栏按钮组
+
+📦 此组件适合集成于管理系统、数据看板等复杂前端应用中。
\ No newline at end of file
diff --git a/aidocs/dynamiccolumn.md b/aidocs/dynamiccolumn.md
new file mode 100644
index 0000000..e4c216f
--- /dev/null
+++ b/aidocs/dynamiccolumn.md
@@ -0,0 +1,173 @@
+# `DynamicColumn` 组件技术文档
+
+> **模块路径**: `bricks.DynamicColumn`  
+> **继承自**: `bricks.Layout`  
+> **用途**: 一个响应式网格布局组件，根据屏幕尺寸动态调整列数和列宽，适用于桌面与移动端。
+
+---
+
+## 概述
+
+`DynamicColumn` 是 Bricks UI 框架中的一个布局类，用于创建基于 CSS Grid 的**动态列布局**。它能够根据设备类型（移动端或桌面端）、字符单位（`charsize`）以及配置参数自动计算并设置网格的列宽与间距，实现响应式设计。
+
+该组件特别适合用于卡片列表、内容流等需要自适应列数的场景。
+
+---
+
+## 构造函数
+
+```js
+new bricks.DynamicColumn(options)
+```
+
+### 参数
+
+| 参数名         | 类型     | 必填 | 默认值 | 描述 |
+|----------------|----------|------|--------|------|
+| `col_cwidth`   | Number   | 否   | 根据 `col_width` 推导 | 列宽度（以字符单位 `charsize` 为基准）。例如：20 表示 20 个字符宽度。 |
+| `col_width`    | Number   | 否   | —      | 固定列宽度（像素值）。若未提供 `col_cwidth`，则使用此值。 |
+| `col_cgap`     | Number   | 否   | `0.5`  | 列之间的间隙（以 `charsize` 为单位）。 |
+| `mobile_cols`  | Number   | 否   | `1`    | 在移动设备竖屏模式下强制显示的列数。 |
+
+> ⚠️ 注意：
+> - 若未传入 `col_cwidth` 且未传入 `col_width`，则默认 `col_cwidth = 20`。
+> - 所有参数均可通过构造选项对象传入。
+
+### 示例
+
+```js
+const layout = new bricks.DynamicColumn({
+  col_cwidth: 25,     // 每列宽 25ch
+  col_cgap: 0.8,      // 列间距 0.8ch
+  mobile_cols: 1      // 移动端强制单列
+});
+```
+
+---
+
+## 方法说明
+
+### `set_column_width()`
+
+重新计算并设置当前容器的 `gridTemplateColumns` 和 `gap` 样式属性，实现动态列宽适配。
+
+#### 逻辑流程
+
+1. 获取当前应用的字符大小 `bricks.app.charsize`。
+2. 计算列间间隙：`gap = charsize × col_cgap`。
+3. 获取当前视口宽高：`screenWidth()` 与 `screenHeight()`。
+4. 判断是否为移动端竖屏：
+   - 如果是，则使用 `mobile_cols` 固定列数，并均分可用宽度；
+   - 否则：
+     - 优先使用 `col_cwidth` × `charsize` 作为最小列宽；
+     - 其次回退到 `col_width` 像素值。
+5. 设置 CSS Grid 属性：
+   ```css
+   grid-template-columns: repeat(auto-fill, minmax(cw + "px", 1fr));
+   gap: gap + "px";
+   ```
+
+#### 触发时机
+
+该方法会在以下事件中被自动调用：
+
+- 组件绑定到父元素时 (`on_parent`)
+- 窗口尺寸变化时 (`resize`)
+- 字符单位发生变化时 (`charsize` 事件，前提是实例具有 `cwidth` 属性)
+
+---
+
+## 样式行为
+
+| CSS 属性 | 值 | 说明 |
+|---------|-----|------|
+| `display` | `grid` | 强制启用 CSS Grid 布局 |
+| `grid-template-columns` | `repeat(auto-fill, minmax(cw, 1fr))` | 自动填充列，每列至少 `cw` 宽度，最多扩展至 1fr |
+| `gap` | 动态计算的像素值 | 列与行之间的间距（由 `col_cgap` × `charsize` 决定） |
+
+> ✅ 提示：使用 `auto-fill` 能确保在空间足够时自动添加新列，无需手动管理断点。
+
+---
+
+## 响应式策略
+
+| 设备环境       | 判断条件                        | 行为 |
+|----------------|----------------------------------|------|
+| 移动端竖屏     | `bricks.is_mobile() && width < height` | 使用 `mobile_cols` 固定列数，宽度均分 |
+| 桌面/横屏设备 | 其他情况                         | 使用 `col_cwidth` 或 `col_width` 作为最小列宽，启用 `minmax` 自动换行 |
+
+---
+
+## 注册信息
+
+```js
+bricks.Factory.register('DynamicColumn', bricks.DynamicColumn);
+```
+
+可通过工厂方式创建实例：
+
+```js
+bricks.Factory.create('DynamicColumn', { ...options });
+```
+
+---
+
+## 使用建议
+
+### 推荐搭配
+- 配合 `bricks.Container` 或其他 `Layout` 子类作为子项使用。
+- 结合 `charsize` 变化监听，实现字体缩放下的布局同步更新。
+
+### 性能提示
+- 避免频繁触发 `set_column_width`，组件已对 `resize` 和 `charsize` 做了事件绑定优化。
+- 如需禁用字符单位监听，可避免设置 `this.cwidth` 属性。
+
+---
+
+## 示例代码
+
+```js
+// 创建一个动态列布局，每列约 20 字符宽，间隔 1ch
+const dynamicCol = new bricks.DynamicColumn({
+  col_cwidth: 20,
+  col_cgap: 1,
+  mobile_cols: 1
+});
+
+// 添加一些内容
+['Item 1', 'Item 2', 'Item 3'].forEach(text => {
+  const item = new bricks.Label({ text });
+  dynamicCol.append(item);
+});
+
+// 插入 DOM
+document.body.appendChild(dynamicCol.dom_element);
+```
+
+---
+
+## 浏览器兼容性
+
+✅ 支持所有现代浏览器（Chrome, Firefox, Safari, Edge）  
+⚠️ 需要支持 CSS Grid Layout Level 1
+
+---
+
+## 版本历史
+
+| 版本 | 修改内容 |
+|------|----------|
+| 1.0  | 初始实现，支持字符单位驱动的动态列布局 |
+
+---
+
+## 相关类
+
+- [`bricks.Layout`](./Layout.md) - 基础布局类
+- [`bricks.app`](../core/app.md) - 应用上下文，提供 `charsize`, `screenWidth()` 等工具
+- [`bricks.is_mobile()`](../utils/is_mobile.md) - 设备检测工具函数
+
+--- 
+
+📝 **维护者**: Bricks UI Team  
+📅 **最后更新**: 2025-04-05
\ No newline at end of file
diff --git a/aidocs/echartsext.md b/aidocs/echartsext.md
new file mode 100644
index 0000000..05bd2ea
--- /dev/null
+++ b/aidocs/echartsext.md
@@ -0,0 +1,301 @@
+# `EchartsExt` 技术文档
+
+> **模块路径**: `bricks.EchartsExt`  
+> **继承自**: `bricks.VBox`  
+> **依赖库**: [Apache ECharts](https://echarts.apache.org/)（需全局引入）
+
+---
+
+## 概述
+
+`bricks.EchartsExt` 是一个基于 `ECharts` 的可扩展图表组件，封装在 `bricks.js` 前端框架中。它继承自 `VBox` 容器类，支持动态数据加载、响应式布局以及点击事件处理，适用于展示多维数据的可视化图表（如柱状图、折线图、饼图等）。
+
+该组件支持从本地数据或远程 URL 加载数据，并能自动将“长格式”数据透视为“宽格式”，便于多系列图表渲染。
+
+---
+
+## 初始化选项（Constructor Options）
+
+```js
+new bricks.EchartsExt({
+  title:        String,     // 图表标题
+  description:  String,     // 图表描述（可选）
+  data_url:     String,     // 远程数据接口地址
+  data_params:  Object,     // 请求参数（附加到 data_url）
+  method:       String,     // HTTP 方法，默认 'GET'
+  user_data:    Array,      // 本地数据数组（优先级高于 data_url）
+  nameField:    String,     // 分组字段名（如：类别名称），默认 'name'
+  valueField:   String,     // 数值字段名（单系列时使用），默认 'value'
+  serieField:   String,     // 系列字段名（用于区分多个数据系列）
+  valueFields:  Array,      // 多数值字段数组（若未设置，则根据 serieField 自动提取）
+  pie_options:  Object,     // 特定于饼图的配置项（可选）
+  idField:      String      // 唯一标识字段，默认 'id'
+})
+```
+
+> ⚠️ 注意：`user_data` 和 `data_url` 二选一。若两者都存在，优先使用 `user_data`。
+
+---
+
+## 属性说明
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `idField` | String | 数据对象唯一标识字段，默认 `'id'` |
+| `nameField` | String | 作为 X 轴或分类维度的字段，默认 `'name'` |
+| `valueField` | String | 主数值字段，默认 `'value'`（仅单系列有效） |
+| `serieField` | String | 区分不同数据系列的字段（例如：“类型”、“年份”） |
+| `valueFields` | Array | 所有需要显示的数据系列名称列表（自动从 `serieField` 提取） |
+| `user_data` | Array | 当前加载的数据集（原始格式） |
+| `data_url` | String | 数据请求地址 |
+| `data_params` | Object | 额外请求参数 |
+| `holder` | `bricks.Filler` | 内部占位容器，用于承载 ECharts 实例 |
+| `chart` | `echarts.ECharts` | ECharts 实例对象 |
+| `method` | String | HTTP 请求方法，默认 `'GET'` |
+
+---
+
+## 方法详解
+
+### `constructor(opts)`
+
+初始化图表组件，执行以下操作：
+
+- 设置默认字段；
+- 创建标题和描述组件；
+- 初始化内部容器 `holder`；
+- 初始化 ECharts 实例；
+- 若存在 `user_data` 则立即渲染；否则尝试通过 `data_url` 异步加载数据；
+- 绑定窗口/元素重绘事件以触发图表 resize。
+
+```js
+this.bind('element_resize', this.chart.resize.bind(this.chart));
+```
+
+---
+
+### `pivotify(data) → Array`
+
+将“长格式”数据转换为“宽格式”数据，便于多系列图表展示。
+
+#### 输入数据示例（长格式）：
+```json
+[
+  { "name": "A", "type": "销量", "value": 100 },
+  { "name": "A", "type": "利润", "value": 30 },
+  { "name": "B", "type": "销量", "value": 150 }
+]
+```
+
+#### 输出结果（宽格式）：
+```json
+[
+  { "name": "A", "销量": 100, "利润": 30 },
+  { "name": "B", "销量": 150 }
+]
+```
+
+#### 处理逻辑：
+1. 提取所有唯一的 `serieField` 值作为新字段；
+2. 按 `nameField` 排序；
+3. 构建以 `nameField` 为键的对象字典；
+4. 将每个记录映射到对应行并填充相应系列值；
+5. 返回对象值数组并排序。
+
+> ✅ 使用场景：当 `serieField` 存在时，自动启用透视功能。
+
+---
+
+### `get_series(data) → Array`
+
+提取数据中所有唯一的系列名称（基于 `this.serieField`）。
+
+#### 示例：
+```js
+data = [
+  { type: 'sales', value: 100 },
+  { type: 'profit', value: 20 },
+  { type: 'sales', value: 80 }
+]
+// get_series(data) → ['sales', 'profit']
+```
+
+返回值用于生成图例（legend）或系列配置。
+
+---
+
+### `render_data()`
+
+根据当前 `user_data` 渲染图表。
+
+#### 步骤：
+1. 若存在 `serieField`，则调用 `pivotify()` 转换数据；
+2. 初始化新的 ECharts 实例（防止内存泄漏）；
+3. 调用 `setup_options(data)` 获取图表配置；
+4. 补充 `grid` 布局配置；
+5. 若有多系列且存在 `legend`，更新其 `data` 字段；
+6. 应用配置到 ECharts 实例；
+7. 绑定点击事件处理器 `click_handle`。
+
+> 🔁 支持热更新：每次调用此方法都会重新绘制图表。
+
+---
+
+### `click_handle(params)`
+
+ECharts 点击事件回调函数。
+
+#### 参数：
+- `params`: ECharts 返回的点击事件参数对象
+
+#### 动作：
+- 打印调试信息至控制台；
+- 触发自定义事件 `'element_click'`，携带原始数据项：
+
+```js
+this.dispatch('element_click', this.user_data[params.dataIndex]);
+```
+
+> 🎯 可用于外部监听数据项点击行为，实现联动交互。
+
+---
+
+### `async render_urldata(params = {})`
+
+异步从远程 URL 加载数据并渲染图表。
+
+#### 流程：
+1. 合并默认参数 `this.data_params` 与传入参数；
+2. 使用 `bricks.HttpJson` 发起 HTTP 请求；
+3. 成功后保存响应数据至 `this.user_data`；
+4. 调用 `render_data()` 渲染图表。
+
+#### 示例请求：
+```js
+await jc.httpcall(this.data_url, {
+  method: this.method || 'GET',
+  params: _params
+});
+```
+
+> ⏱️ 默认延迟 0.1 秒调度，避免构造期间 DOM 未就绪。
+
+---
+
+## 事件（Events）
+
+| 事件名 | 触发时机 | 携带数据 |
+|--------|----------|---------|
+| `element_click` | 用户点击图表中的某个数据点 | 对应的原始数据项（来自 `user_data`） |
+| `element_resize` | 元素尺寸变化时（由父容器触发） | —— |
+
+可通过 `bind()` 监听这些事件：
+
+```js
+chart.bind('element_click', function(dataItem) {
+  console.log('Clicked:', dataItem);
+});
+```
+
+---
+
+## 数据结构要求
+
+### 本地数据（`user_data`）格式
+
+```json
+[
+  {
+    "name": "类别A",
+    "value": 120,
+    "type": "线上"
+  },
+  {
+    "name": "类别A",
+    "value": 80,
+    "type": "线下"
+  },
+  ...
+]
+```
+
+- 必须是对象数组；
+- 至少包含 `nameField` 和 `valueField` 字段；
+- 若使用多系列，需提供 `serieField` 字段。
+
+---
+
+## 样式与布局
+
+- 图表容器自动适应父元素大小；
+- `grid` 配置留白 3%，确保标签不被裁剪；
+- 支持响应式设计，绑定 `element_resize` 事件自动调整图表尺寸。
+
+---
+
+## 使用示例
+
+### 示例 1：使用本地数据创建多系列柱状图
+
+```js
+var chart = new bricks.EchartsExt({
+  title: "销售统计",
+  description: "各区域线上线下销售额对比",
+  user_data: [
+    { name: "北京", type: "线上", value: 200 },
+    { name: "北京", type: "线下", value: 150 },
+    { name: "上海", type: "线上", value: 180 },
+    { name: "上海", type: "线下", value: 170 }
+  ],
+  nameField: "name",
+  valueField: "value",
+  serieField: "type"
+});
+
+chart.bind('element_click', function(item) {
+  alert("点击了：" + item.name);
+});
+```
+
+### 示例 2：从 API 加载数据
+
+```js
+var chart = new bricks.EchartsExt({
+  title: "实时订单量",
+  data_url: "/api/orders",
+  data_params: { period: "today" },
+  nameField: "hour",
+  valueField: "count",
+  method: "GET"
+});
+```
+
+---
+
+## 注意事项
+
+1. **ECharts 必须已全局加载**，否则 `echarts.init` 会报错；
+2. `setup_options(data)` 方法需子类实现，用于定义具体图表类型（如 bar、line、pie）；
+3. 若未定义 `serieField`，则不会进行数据透视；
+4. `valueFields` 若手动指定，则忽略自动提取逻辑；
+5. 建议对大数据集做分页或聚合处理，避免性能问题。
+
+---
+
+## 调试提示
+
+- 查看浏览器控制台输出 `opts=` 可检查最终传递给 ECharts 的配置；
+- 确保 `this.holder.dom_element` 已正确挂载且非空；
+- 检查网络请求是否成功返回合法 JSON 数据。
+
+---
+
+## 版本信息
+
+- **Bricks Framework**: v1.x+
+- **ECharts 支持版本**: ≥ 5.0
+- **兼容性**: 支持现代浏览器（Chrome / Firefox / Edge / Safari）
+
+---
+
+> 💡 提示：建议结合 `bricks.Layout` 系统使用，实现复杂仪表盘布局。
\ No newline at end of file
diff --git a/aidocs/factory.md b/aidocs/factory.md
new file mode 100644
index 0000000..3b4e73d
--- /dev/null
+++ b/aidocs/factory.md
@@ -0,0 +1,162 @@
+# Bricks 工厂模式技术文档
+
+## 概述
+
+`bricks.Factory` 是一个基于单例模式的工厂类，用于注册和获取组件（或“小部件”）对象。它提供了一个全局可访问的注册表，允许动态地注册命名的组件类或对象，并通过名称进行检索。
+
+该实现是 `Bricks` 前端框架/库的一部分，旨在统一管理可复用的 UI 组件或其他功能模块。
+
+---
+
+## 代码结构
+
+```javascript
+var bricks = window.bricks || {};
+class Factory_ {
+    constructor() {
+        this.widgets_kv = new Object();
+        this.widgets_kv['_t_'] = 1;
+    }
+
+    register(name, widget) {
+        this.widgets_kv[name] = widget;
+    }
+
+    get(name) {
+        if (this.widgets_kv.hasOwnProperty(name)) {
+            return this.widgets_kv[name];
+        }
+        return null;
+    }
+}
+bricks.Factory = new Factory_();
+```
+
+---
+
+## 核心类：`Factory_`
+
+### 构造函数 `constructor()`
+
+初始化一个空的对象 `widgets_kv`，用于存储注册的组件。
+
+#### 初始化内容：
+- `this.widgets_kv = new Object()`  
+  创建一个普通对象作为键值对存储容器。
+- `this.widgets_kv['_t_'] = 1`  
+  预留字段，可能用于调试、版本标识或检测对象是否已被初始化（用途未明确，但不影响主流程）。
+
+> ⚠️ 注意：使用 `new Object()` 而非 `{}` 仅为风格选择，功能一致。
+
+---
+
+### 方法说明
+
+#### `register(name: string, widget: any): void`
+
+将指定名称与组件（类、函数或对象）注册到工厂中。
+
+##### 参数：
+| 参数名   | 类型   | 描述 |
+|---------|--------|------|
+| `name`  | string | 注册的唯一名称（键），用于后续查找 |
+| `widget`| any    | 要注册的组件，通常为类构造函数或配置对象 |
+
+##### 行为：
+- 直接赋值：`this.widgets_kv[name] = widget`
+- 若名称已存在，则覆盖旧值
+
+##### 示例：
+```js
+class MyWidget { /* ... */ }
+bricks.Factory.register('my-widget', MyWidget);
+```
+
+---
+
+#### `get(name: string): any | null`
+
+根据名称从工厂中获取已注册的组件。
+
+##### 参数：
+| 参数名   | 类型   | 描述 |
+|---------|--------|------|
+| `name`  | string | 要查询的组件名称 |
+
+##### 返回值：
+- 如果存在该名称的组件，返回对应值；
+- 否则返回 `null`
+
+> 使用 `hasOwnProperty` 检查避免原型链污染风险。
+
+##### 示例：
+```js
+const WidgetClass = bricks.Factory.get('my-widget');
+if (WidgetClass) {
+    const instance = new WidgetClass();
+}
+```
+
+---
+
+## 全局实例：`bricks.Factory`
+
+通过以下语句暴露为全局单例：
+
+```js
+bricks.Factory = new Factory_();
+```
+
+确保在整个应用中只有一个 `Factory` 实例，所有模块共享同一注册表。
+
+> 利用 `window.bricks || {}` 确保命名空间安全，防止覆盖已有变量。
+
+---
+
+## 设计模式
+
+- **单例模式（Singleton Pattern）**  
+  `Factory_` 类仅被实例化一次，全局共享状态。
+  
+- **工厂模式（Factory Pattern）**  
+  提供统一接口来创建对象，解耦对象的使用与创建过程。
+
+---
+
+## 使用场景
+
+适用于需要动态加载或按需获取组件的系统，例如：
+
+- UI 组件库注册与调用
+- 插件系统
+- 模块化前端架构中的依赖查找
+
+---
+
+## 注意事项
+
+1. **名称冲突**  
+   `register` 不检查重名，后注册者会覆盖前者，请确保命名唯一性。
+
+2. **安全性**  
+   当前未对输入参数做类型校验，建议在生产环境中添加防御性编程措施。
+
+3. **性能**  
+   使用普通对象作为 map，在现代 JS 引擎中对于中等规模键集表现良好。若需大规模注册，可考虑改用 `Map`。
+
+4. **扩展建议**
+   - 可增加 `unregister(name)` 方法以支持注销组件
+   - 可增加 `list()` 方法返回所有注册项列表用于调试
+
+---
+
+## 版本信息
+
+- 创建时间：未知（根据代码推断为早期 JS 模块化方案）
+- 兼容性：支持 ES6+ 环境，可在浏览器中直接运行
+
+---
+
+## 总结
+
+`bricks.Factory` 是一个轻量级、高效的组件注册与获取机制，适用于构建模块化、可扩展的前端系统。其简洁的设计使其易于理解和集成，是 `Bricks` 框架基础设施的重要组成部分。
\ No newline at end of file
diff --git a/aidocs/floaticonbar.md b/aidocs/floaticonbar.md
new file mode 100644
index 0000000..4cfcf08
--- /dev/null
+++ b/aidocs/floaticonbar.md
@@ -0,0 +1,321 @@
+# `bricks.IconBar` 及相关组件技术文档
+
+---
+
+## 概述
+
+`bricks.IconBar` 是一个基于 `bricks.HBox` 的 UI 组件类，用于创建水平排列的图标工具栏。它支持动态图标、点击事件分发、响应式尺寸调整等功能。该模块还包含多个扩展类：
+
+- `bricks.IconTextBar`：带文本标签的图标栏。
+- `bricks.FloatIconBar`：浮动式图标栏，鼠标悬停时显示完整图标组。
+- `bricks.FloatIconTextBar`：结合浮动与图文混合的增强型工具栏。
+
+这些组件常用于构建轻量级、可定制的工具栏或操作面板。
+
+---
+
+## 基础结构
+
+```js
+var bricks = window.bricks || {};
+```
+
+确保 `bricks` 全局命名空间存在，避免覆盖已有内容。
+
+---
+
+## 1. `bricks.IconBar`
+
+### 类继承关系
+```js
+class extends bricks.HBox
+```
+
+继承自 `HBox`（水平布局容器），实现横向排列子控件。
+
+### 配置参数 (`opts`)
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `cheight` | Number | `2` | 子项高度倍率（相对于字符单位） |
+| `rate` | Number | `1` | 缩放比例因子 |
+| `margin` | String | `'10px'` | 图标之间的左右边距 |
+| `tools` | Array | `[]` | 工具定义数组，每个元素为一个工具描述对象 |
+
+#### `tools` 数组项结构
+| 属性 | 类型 | 是否必需 | 说明 |
+|------|------|----------|------|
+| `name` | String | 否 | 图标的唯一标识名称（用于事件分发和 DOM ID） |
+| `icon` | String | 是（非 blankicon） | SVG 图标 URL 或资源路径 |
+| `rate` | Number | 否 | 单独设置该图标的缩放比例（优先于全局 rate） |
+| `dynsize` | Boolean | 否 | 是否启用动态尺寸调整 |
+| `tip` | String | 否 | 提示文本（暂未在 IconBar 中直接使用） |
+
+> 特殊情况：若 `name === 'blankicon'`，则生成空白占位符图标。
+
+### 构造函数行为
+
+```js
+constructor(opts)
+```
+
+1. **默认值填充**：
+   - 若未指定 `cheight`，默认设为 `2`
+   - 若未指定 `rate`，默认设为 `1`
+
+2. **调用父类构造器**：
+   ```js
+   super(opts);
+   ```
+
+3. **样式设置**：
+   - 添加 CSS 类名 `'childrensize'`
+   - 设置主轴对齐方式为居中（`alignItems: center`）
+
+4. **遍历 `tools` 创建子控件**：
+   - 复制每个工具配置并补充通用属性（如 `cheight`, `cwidth`, `dynsize`）
+   - 调用 `build_item(opts)` 创建具体控件
+   - 设置左右 margin 和 cursor 样式为 pointer
+   - 若有 `name`，设置对应 widget 的 ID
+   - 绑定点击事件并通过 `regen_event` 分发事件
+   - 将控件加入容器
+
+5. **内部高度记录**：
+   - 使用 `this.height_int` 记录所有子控件中的最大高度（像素值），便于外部布局参考。
+
+---
+
+### 方法详解
+
+#### `build_item(opts) → Widget`
+
+根据配置创建单个图标控件。
+
+##### 行为逻辑：
+- 计算实际高度：`h = bricks.app.charsize * rate * opts.cheight`
+- 更新 `this.height_int` 以保持最大高度
+- 判断是否为 `blankicon`：
+  - 是 → 返回 `new bricks.BlankIcon({...})`
+  - 否 → 使用 `opts.icon` 作为 `url` 创建 `bricks.Svg` 实例
+- 绑定点击事件到 `regen_event(desc, event)`
+- 返回创建的控件
+
+#### `regen_event(desc, event)`
+
+处理图标点击事件，并触发两个事件：
+
+```js
+this.dispatch(desc.name, desc);        // 以 name 为事件类型分发
+this.dispatch('command', desc);        // 统一命令事件
+```
+
+同时阻止事件冒泡和默认行为：
+
+```js
+event.preventDefault();
+event.stopPropagation();
+```
+
+> 此设计适用于菜单/按钮点击后不希望影响页面其他部分的操作场景。
+
+---
+
+## 2. `bricks.IconTextBar`（图文混合图标栏）
+
+### 类继承关系
+```js
+class extends bricks.IconBar
+```
+
+重写了 `build_item` 方法以支持图标+文字组合。
+
+### `build_item(opts)` 实现细节
+
+返回一个 `HBox` 容器，内含：
+
+1. **SVG 图标（可选）**
+   - 来源：`opts.icon`
+   - 属性包括 `rate`, `dynsize`
+
+2. **文本标签（可选）**
+   - 使用 `bricks.Text` 显示 `opts.label`
+   - 支持国际化（`i18n: true`）、自动换行（`wrap: true`）、左对齐（`haligh: 'left'`）
+
+3. **整体包装**
+   - 包裹在一个 `HBox` 中，宽度自适应，高度自动计算
+   - 绑定点击事件至 `regen_event(opts)`
+   - 更新 `height_int`（基于 `charsize * rate`）
+
+> ⚠️ 注意：图标与文本共存时垂直居中对齐由外层 HBox 控制。
+
+---
+
+## 3. `bricks.FloatIconBar`（浮动图标栏）
+
+### 类继承关系
+```js
+class extends bricks.HBox
+```
+
+实现“仅显示浮出按钮，悬停时展开全部图标”的交互模式。
+
+### 配置参数 (`opts`)
+同 `IconBar`，但只显示一个小浮点按钮，其余图标隐藏。
+
+### 构造函数逻辑
+
+1. 创建浮出按钮：
+   ```js
+   this.float_w = new bricks.Svg({ url: bricks_resource('imgs/float-out.png') });
+   ```
+   - 绑定 `mousemove` 事件显示图标栏
+   - 添加到容器
+
+2. 创建图标主体：
+   ```js
+   this.icons_box = this.build_bar(opts);
+   ```
+   - 默认调用 `new bricks.IconBar(opts)`
+   - 初始隐藏（`display: none`）
+
+3. 设置容器高度等于 `icons_box.height_int`
+4. 绑定全局点击事件隐藏图标栏（通过 `Body.click`）
+
+### 方法说明
+
+| 方法 | 功能 |
+|------|------|
+| `build_bar(opts)` | 工厂方法，创建内部图标栏实例（可被子类重写） |
+| `show_icons()` | 显示图标栏（`display: flex`） |
+| `hide_icons()` | 隐藏图标栏（`display: none`） |
+
+> 📌 交互逻辑：鼠标移上浮点按钮 → 显示图标；点击任意空白区域 → 隐藏图标。
+
+---
+
+## 4. `bricks.FloatIconTextBar`（浮动图文栏）
+
+### 类继承关系
+```js
+class extends bricks.FloatIconBar
+```
+
+扩展 `FloatIconBar`，使其内部使用 `IconTextBar` 替代 `IconBar`。
+
+### 核心重写方法
+
+```js
+build_bar(opts) {
+    return new bricks.IconTextBar(opts);
+}
+```
+
+> ✅ 效果：浮出后显示带文字说明的图标按钮组，适合需要语义化提示的场景。
+
+---
+
+## 工厂注册
+
+以下语句将各组件注册到 `bricks.Factory`，支持通过字符串名称动态创建实例：
+
+```js
+bricks.Factory.register('IconBar', bricks.IconBar);
+bricks.Factory.register('IconTextBar', bricks.IconTextBar);
+bricks.Factory.register('FloatIconBar', bricks.FloatIconBar);
+bricks.Factory.register('FloatIconTextBar', bricks.FloatIconTextBar);
+```
+
+### 使用示例（工厂方式）
+```js
+var bar = bricks.Factory.create('IconTextBar', {
+    tools: [
+        { name: 'save', icon: '/icons/save.svg', label: 'Save File' },
+        { name: 'print', icon: '/icons/print.svg', label: 'Print' }
+    ],
+    margin: '8px',
+    rate: 1.2
+});
+```
+
+---
+
+## 示例配置
+
+### 简单图标栏
+```js
+new bricks.IconBar({
+    cheight: 2,
+    rate: 1,
+    margin: '12px',
+    tools: [
+        { name: 'home', icon: '/icons/home.svg', tip: 'Go Home' },
+        { name: 'settings', icon: '/icons/settings.svg' },
+        { name: 'blankicon' }, // 占位符
+        { name: 'logout', icon: '/icons/logout.svg' }
+    ]
+});
+```
+
+### 图文混合栏
+```js
+new bricks.IconTextBar({
+    rate: 1.1,
+    tools: [
+        { name: 'new', icon: '/icons/new.svg', label: 'New', tip: 'Create new file' },
+        { name: 'open', icon: '/icons/open.svg', label: 'Open' },
+        { name: 'help', label: 'Help', icon: '/icons/help.svg' }
+    ]
+});
+```
+
+### 浮动图文工具栏
+```js
+new bricks.FloatIconTextBar({
+    tools: [
+        { name: 'cut', icon: '/icons/cut.svg', label: 'Cut' },
+        { name: 'copy', icon: '/icons/copy.svg', label: 'Copy' },
+        { name: 'paste', icon: '/icons/paste.svg', label: 'Paste' }
+    ],
+    rate: 1
+});
+```
+
+---
+
+## 设计特点总结
+
+| 特性 | 描述 |
+|------|------|
+| 🔧 **模块化设计** | 所有功能拆分为可复用类，便于扩展 |
+| 🖱️ **交互友好** | 支持点击、悬停展开、事件拦截 |
+| 📏 **响应式尺寸** | 基于 `charsize` 和 `rate` 实现相对缩放 |
+| 🔔 **事件驱动** | 通过 `dispatch` 发送命名事件，解耦 UI 与业务逻辑 |
+| 🧩 **工厂模式支持** | 可通过字符串动态创建组件 |
+
+---
+
+## 注意事项
+
+1. **依赖前提**：
+   - 必须已加载 `bricks.HBox`, `bricks.Svg`, `bricks.Text`, `bricks.BlankIcon`, `bricks.Body`
+   - `bricks.app.charsize` 需已初始化
+   - `bricks_resource()` 函数需可用（用于资源路径解析）
+
+2. **性能建议**：
+   - 工具数量较多时建议使用 `FloatIconBar` 减少视觉干扰
+   - 避免频繁重建整个 `IconBar`，应缓存实例
+
+3. **样式定制**：
+   - 推荐通过 `set_style()` 或外部 CSS 修改外观
+   - 不推荐直接修改内部 DOM 结构
+
+---
+
+## 版本信息
+
+- **作者**：Bricks Framework Team
+- **版本**：1.0
+- **最后更新**：2025年4月5日
+
+--- 
+
+📌 **文档结束**
\ No newline at end of file
diff --git a/aidocs/form.md b/aidocs/form.md
new file mode 100644
index 0000000..91eadc7
--- /dev/null
+++ b/aidocs/form.md
@@ -0,0 +1,353 @@
+# Bricks.js 表单模块技术文档
+
+> 本文档描述了 `bricks` 框架中表单相关组件的实现逻辑、结构与使用方式。该模块提供了灵活的表单构建能力，支持动态字段渲染、数据校验、提交处理及工具栏集成。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [核心变量](#核心变量)
+- [核心方法](#核心方法)
+- [类说明](#类说明)
+  - [`FieldGroup`](#fieldgroup)
+  - [`FormBody`](#formbody)
+  - [`FormBase`](#formbase)
+  - [`InlineForm`](#inlineform)
+  - [`Form`](#form)
+- [工厂注册](#工厂注册)
+- [使用示例](#使用示例)
+
+---
+
+## 概述
+
+本模块为 `bricks.js` 提供了一套完整的表单系统，包含以下功能：
+
+- 动态生成表单字段（支持嵌套分组）
+- 支持文件上传（需使用 `FormData`）
+- 自动化工具栏（提交、重置、取消按钮）
+- 数据获取与验证
+- 提交前后事件分发
+- 多布局支持（水平/垂直输入框）
+
+主要适用于 Web 端复杂表单场景，如配置页、编辑器、数据录入等。
+
+---
+
+## 核心变量
+
+### `bricks.need_formdata_fields`
+
+```js
+bricks.need_formdata_fields = ['file', 'video', 'audio'];
+```
+
+**说明：**  
+指定哪些字段类型需要通过 `FormData` 提交（例如文件上传类字段）。这些字段将触发表单启用 `multipart/form-data` 编码模式。
+
+---
+
+## 核心方法
+
+### `show_resp_message_or_error(resp)`
+
+```js
+bricks.show_resp_message_or_error = async function(resp){...}
+```
+
+**参数：**
+- `resp`: `Response` 对象（来自 `fetch` 请求）
+
+**功能：**
+1. 解析响应体为 JSON。
+2. 调用 `widgetBuild` 将返回的 UI 描述渲染到页面主体中。
+
+**用途：**  
+用于处理服务端返回的动态 UI 或错误信息并展示。
+
+---
+
+## 类说明
+
+### `FieldGroup`
+
+负责根据字段定义递归构建表单控件。
+
+#### 构造函数
+```js
+new FieldGroup(opts)
+```
+- `opts`: 配置对象（目前未实际使用）
+
+#### 方法：`build_fields(form, parent, fields)`
+
+| 参数     | 类型       | 说明 |
+|----------|------------|------|
+| `form`   | Form 实例  | 当前所属表单对象 |
+| `parent` | Widget     | 容器组件（如 VBox/HBox） |
+| `fields` | Array      | 字段数组 |
+
+**行为说明：**
+
+- 使用 `DynamicColumn` 实现响应式列布局（移动端默认两列）。
+- 若遇到 `uitype: 'group'` 的字段，则递归构建其内部字段，并插入新列。
+- 非隐藏字段创建 `VBox` 或 `HBox` 包裹标签和输入控件。
+- 所有输入控件由 `Input.factory(field)` 创建，并存入 `form.name_inputs`。
+- 若字段类型在 `need_formdata_fields` 中，设置 `form.need_formdata = true`。
+
+---
+
+### `FormBody`
+
+继承自 `VScrollPanel`，是表单内容区域的核心容器。
+
+#### 构造函数
+```js
+new FormBody(form, opts)
+```
+
+**初始化操作：**
+- 设置宽高为 100%
+- 初始化 `name_inputs` 映射
+- 创建 `FieldGroup` 渲染非文本字段
+- 调用 `build_text_fields()` 渲染文本字段
+
+#### 方法：`build_text_fields()`
+
+遍历 `form.textfields`，对每个字段：
+- 创建标签文字 (`Text`)
+- 创建只读文本控件 (`UiText`)
+- 包装成 `VBox` 并添加至容器
+- 注册到 `form.name_inputs` 中以便后续取值
+
+> **注意：** `text` 类型字段不参与编辑，仅用于显示。
+
+---
+
+### `FormBase`
+
+表单基类，提供通用功能（继承自 `Layout`）。
+
+#### 属性
+
+| 属性名            | 类型    | 说明 |
+|-------------------|--------|------|
+| `name_inputs`     | Object | 存储字段名 → 控件实例映射 |
+| `submit_changed`  | Boolean| 是否仅提交变更字段 |
+| `origin_data`     | Object | 初始数据快照（用于比对变化） |
+| `submit_url`      | String | 提交地址 |
+| `method`          | String | HTTP 方法，默认 `'POST'` |
+| `toolbar`         | Object | 工具栏配置扩展 |
+
+#### 方法
+
+##### `build_toolbar(widget)`
+动态构建顶部工具栏（含“提交”、“重置”、“取消”按钮），支持自定义扩展。
+
+- 默认图标路径由 `bricks_resource()` 加载。
+- 使用 `IconTextBar` 组件呈现按钮条。
+- 绑定 `command` 事件到 `command_handle`。
+
+##### `command_handle(event)`
+处理工具栏命令事件：
+
+| 命令名     | 行为 |
+|-----------|------|
+| `submit`  | 触发 `validation()` |
+| `reset`   | 调用 `reset_data()` |
+| `cancel`  | 触发 `dispatch('cancel')` |
+| 其他      | 若有 `action` 则执行事件处理器；否则直接 `dispatch(name)` |
+
+##### `reset_data()`
+重置所有输入控件为其初始值（调用各控件的 `reset()` 方法）。
+
+##### `_getValue()`
+收集所有字段值，进行必填校验：
+
+- 忽略无权访问的属性（`hasOwnProperty`）
+- 调用 `getValue()` 获取控件值
+- 必填项为空时弹出错误提示并聚焦
+- 返回合并后的数据对象
+
+> ⚠️ 若校验失败则中断并返回 `undefined`
+
+##### `getValue()`
+优先返回缓存的 `this.data`，否则调用 `get_formdata()`。
+
+##### `get_formdata()`
+构建 `FormData` 实例：
+
+- 遍历所有控件，调用 `set_formdata(data)` 写入数据
+- 若启用了 `submit_changed`，跳过未修改字段
+- 忽略值为 `null` 的字段
+- 返回 `FormData` 或 `null`（无变更）
+
+##### `validation()`
+异步提交流程控制：
+
+1. 显示加载动画（`Running` 组件）
+2. 获取 `FormData`
+3. 分发 `submit` 事件
+4. 若设置了 `submit_url`，发起 HTTP 请求
+5. 成功后分发 `submited` 事件，传入响应对象
+6. 出错时捕获异常并输出日志
+7. 隐藏加载动画
+
+##### `save_origin_data()`
+保存当前所有字段值作为原始状态，用于后续变更判断。
+
+---
+
+### `InlineForm`
+
+轻量级内联表单，适合嵌入其他组件内部。
+
+#### 特性：
+- 不包含标题或描述
+- 直接渲染字段 + 工具栏
+- 自动保存初始数据
+
+#### 构造函数
+```js
+new InlineForm(opts)
+```
+
+**行为：**
+- 设置宽高 100%，开启滚动
+- 调用 `FieldGroup.build_fields()` 渲染 `opts.fields`
+- 添加工具栏到第一个子容器
+- 保存初始数据
+
+---
+
+### `Form`
+
+完整表单组件，具备标题、描述、分栏、工具栏等功能。
+
+#### 配置选项（`opts`）
+
+| 参数           | 类型      | 说明 |
+|----------------|----------|------|
+| `title`        | String   | 表单标题（可国际化） |
+| `description`  | String   | 表单描述文本 |
+| `notoolbar`    | Boolean  | 是否隐藏工具栏，默认 `false` |
+| `input_layout` | String   | 输入框布局 `"VBox"`（默认）或 `"HBox"` |
+| `fields`       | Array    | 字段定义数组 |
+| `submit_url`   | String   | 提交 URL |
+| `method`       | String   | HTTP 方法（GET/POST） |
+| `toolbar`      | Object   | 自定义工具栏配置 |
+
+#### 构造流程
+
+1. 设置尺寸与滚动
+2. 添加标题（若有）
+3. 添加描述（若有）
+4. 添加填充容器 `Filler`
+5. 分离 `text` 与其他字段
+6. 创建 `FormBody` 渲染主体内容
+7. 条件性构建工具栏
+8. 保存初始数据
+
+---
+
+## 工厂注册
+
+```js
+bricks.Factory.register('InlineForm', bricks.InlineForm);
+bricks.Factory.register('Form', bricks.Form);
+```
+
+允许通过字符串名称动态创建组件实例，便于模板化渲染。
+
+---
+
+## 使用示例
+
+### 定义一个简单表单
+
+```js
+var form = new bricks.Form({
+  title: "User Profile",
+  description: "Please fill in your information.",
+  submit_url: "/api/user/update",
+  method: "POST",
+  input_layout: "VBox",
+  fields: [
+    { name: "username", label: "Username", uitype: "text_input", required: true },
+    { name: "email", label: "Email", uitype: "email", required: true },
+    { name: "avatar", label: "Avatar", uitype: "file" },
+    { name: "bio", label: "Bio", uitype: "textarea" },
+    {
+      uitype: "group",
+      fields: [
+        { name: "phone", label: "Phone", uitype: "tel" },
+        { name: "age", label: "Age", uitype: "number" }
+      ]
+    }
+  ]
+});
+
+// 监听提交事件
+form.bind('submit', function(data){
+  console.log("Submitting:", data);
+});
+
+form.bind('submited', function(resp){
+  alert("Saved successfully!");
+});
+```
+
+### 内联表单示例
+
+```js
+var inline = new bricks.InlineForm({
+  fields: [
+    { name: "name", label: "Name", uitype: "text_input" },
+    { name: "status", label: "Status", uitype: "select", options: [...] }
+  ],
+  toolbar: {
+    tools: [
+      { icon: "...", name: "custom", label: "Custom Action", action: "doSomething" }
+    ]
+  }
+});
+
+inline.bind('command:custom', function(){ ... });
+```
+
+---
+
+## 附录：字段定义格式
+
+```json
+[
+  {
+    "name": "field_name",
+    "label": "Display Label",
+    "uitype": "text_input|email|file|group|hide|...",
+    "required": true,
+    "value": "default_value",
+    "removable": false,
+    "icon": "optional_icon_path"
+  }
+]
+```
+
+其中：
+- `group`: 可嵌套子字段
+- `text`: 仅展示，不可编辑
+- `hide`: 隐藏字段（但仍会渲染占位）
+
+---
+
+## 注意事项
+
+- 文件上传字段必须使用 `FormData`，确保 `submit_url` 接口支持 `multipart/form-data`。
+- 所有文本标签建议启用 `i18n: true` 实现多语言支持。
+- 自定义控件需实现 `getValue()` 和 `set_formdata(formData)` 接口。
+- 错误提示依赖 `bricks.Error` 组件，请确保已加载。
+
+---
+
+> 📚 更多组件参考请查阅 [Bricks.js 官方文档](https://github.com/your-bricks-project)。
\ No newline at end of file
diff --git a/aidocs/gobang.md b/aidocs/gobang.md
new file mode 100644
index 0000000..374b096
--- /dev/null
+++ b/aidocs/gobang.md
@@ -0,0 +1,283 @@
+# `bricks.Gobang` 技术文档
+
+> **五子棋游戏组件** —— 基于 `bricks.js` 框架实现的可交互五子棋界面控件。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [类结构](#类结构)
+  - [`bricks.GobangPoint`](#bricksgobangpoint)
+  - [`bricks.Gobang`](#bricksgobang)
+- [API 参考](#api-参考)
+  - [`GobangPoint` 构造函数与方法](#gobangpoint-构造函数与方法)
+  - [`Gobang` 构造函数与方法](#gobang-构造函数与方法)
+- [事件绑定](#事件绑定)
+- [图像资源管理](#图像资源管理)
+- [布局与自适应](#布局与自适应)
+- [使用示例](#使用示例)
+
+---
+
+## 概述
+
+`bricks.Gobang` 是一个基于 `bricks.js` UI 框架开发的五子棋（Gomoku）游戏界面组件。它包含两个核心类：
+
+- `bricks.GobangPoint`：表示棋盘上的单个格子，用于显示空、黑子或白子状态，并支持鼠标悬停反馈。
+- `bricks.Gobang`：主控件，负责构建 15×15 的棋盘布局、管理棋子状态、响应尺寸变化并为后续 AI/玩家逻辑提供接口。
+
+该组件具备良好的可扩展性，可用于人机对战、双人对战或多智能体博弈系统。
+
+---
+
+## 类结构
+
+### `bricks.GobangPoint`
+
+继承自 `bricks.Image`，代表棋盘上一个可交互的点位。
+
+#### 属性说明
+
+| 属性名      | 类型   | 描述 |
+|-----------|--------|------|
+| `p_status` | Number | 棋子状态：`0`=空, `1`=黑子, `2`=白子 |
+| `p_x`      | Number | 横向坐标（列），取值范围 `1–15` |
+| `p_y`      | Number | 纵向坐标（行），取值范围 `1–15` |
+
+> 注：坐标系以左上角为 `(1,1)`，右下角为 `(15,15)`。
+
+#### 构造函数
+
+```js
+new bricks.GobangPoint({
+  p_status: 0,
+  p_x: x,
+  p_y: y,
+  tip: '(x,y)'
+})
+```
+
+##### 参数
+
+| 参数       | 类型   | 必填 | 说明 |
+|----------|--------|------|------|
+| `p_status` | Number | 是   | 初始状态 |
+| `p_x`      | Number | 是   | X 坐标 |
+| `p_y`      | Number | 是   | Y 坐标 |
+| `tip`      | String | 否   | 鼠标提示文本，默认为 `(x,y)` |
+
+#### 方法
+
+##### `.calc_url()`
+
+根据当前 `p_status`, `p_x`, `p_y` 计算对应的图片路径。
+
+- 边缘位置使用特定前缀：
+  - 上边：`t`
+  - 下边：`b`
+  - 左边：`l`
+  - 右边：`r`
+  - 中间区域：`c`
+
+- 状态后缀：
+  - `empty`: 空格
+  - `black`: 黑子
+  - `white`: 白子
+
+**输出格式：**
+
+```
+imgs/[one][two]_[state].png
+```
+
+例如：`imgs/tl_empty.png`, `imgs/cc_black.png`
+
+> 使用 `bricks_resource(name)` 获取实际资源 URL。
+
+##### `.set_current_position(flg, event)`
+
+处理鼠标进入/离开事件，设置 CSS 类控制视觉高亮。
+
+- `flg === true` → 移除 `curpos` 样式类（显示高亮）
+- `flg === false` → 添加 `curpos` 类（取消高亮）
+
+> 实际行为依赖于样式表中 `.curpos` 的定义。
+
+##### `.getValue()`
+
+返回当前点的状态对象。
+
+```js
+{
+  status: this.p_status,
+  x: this.p_x,
+  y: this.p_y
+}
+```
+
+##### `.str()`
+
+调试用字符串输出，格式为 `(status,x,y)`。
+
+---
+
+### `bricks.Gobang`
+
+主游戏容器，继承自 `bricks.VBox`，自动创建 15×15 棋盘。
+
+#### 构造函数
+
+```js
+new bricks.Gobang(opts)
+```
+
+初始化棋盘，渲染空白格子，并开始第一轮回合（默认黑方先行）。
+
+#### 内部属性
+
+| 属性       | 类型     | 说明 |
+|----------|----------|------|
+| `filler` | Filler   | 占位容器，用于监听尺寸变化 |
+| `area`   | Array[Array[GobangPoint]] | 二维数组，存储所有 `GobangPoint` 实例 |
+| `player` | Object   | （预留）玩家配置信息 |
+
+##### 玩家配置结构（未来扩展）
+
+```js
+{
+  black_player: {
+    name: "Player1",
+    type: "user", // 或 "llm"
+    url: "",      // AI 接口地址
+    delay: 1,     // 响应延迟（秒）
+    params: {}    // 自定义参数
+  },
+  white_player: { ... }
+}
+```
+
+#### 方法
+
+##### `.render_empty_area()`
+
+创建 15×15 的棋盘网格：
+
+- 创建外层垂直盒子 (`VBox`)
+- 每行新建一个水平盒子 (`HBox`)
+- 在每个格子中添加 `GobangPoint(p_status=0)`
+- 将其组织成二维数组 `this.area[i][j]`，其中 `i = p_y - 1`, `j = p_x - 1`
+
+最终将整个棋盘加入 `this.filler` 容器。
+
+##### `.resize_area()`
+
+响应容器大小变化，动态调整每个棋盘点的宽高，保持正方形且填满可用空间。
+
+- 计算最小边长：`Math.min(clientWidth, clientHeight)`
+- 单元格尺寸：`size = min_side / 15`
+- 遍历 `this.area` 设置每个 `GobangPoint` 的样式宽高
+
+> 绑定在 `filler` 的 `element_resize` 事件上。
+
+##### `.inform_go(party)`
+
+通知某一方落子（如 `'black'` 或 `'white'`）。此方法目前为空，作为钩子供子类或外部逻辑重写。
+
+典型用途：
+- 触发 AI 思考
+- 更新 UI 提示
+- 发送网络请求
+
+---
+
+## 事件绑定
+
+| 元素 | 事件 | 回调 | 说明 |
+|------|------|-------|------|
+| `GobangPoint` | `mouseover` | `set_current_position(true)` | 显示悬停效果 |
+| `GobangPoint` | `mouseout`  | `set_current_position(false)` | 隐藏悬停效果 |
+| `filler` | `element_resize` | `resize_area()` | 自动适配棋盘尺寸 |
+
+---
+
+## 图像资源管理
+
+通过 `bricks_resource(name)` 函数加载图像资源。建议准备以下命名规则的 PNG 图片：
+
+```
+imgs/
+├── tl_empty.png    ── 左上角空格
+├── tc_empty.png    ── 上边缘中间空格
+├── tr_empty.png    ── 右上角空格
+├── cl_empty.png    ── 左边缘中间空格
+├── cc_empty.png    ── 中央空格
+├── cr_empty.png    ── 右边缘中间空格
+├── bl_empty.png    ── 左下角空格
+├── bc_empty.png    ── 下边缘中间空格
+├── br_empty.png    ── 右下角空格
+│
+├── **_black.png     ── 所有位置的黑子版本
+└── **_white.png     ── 所有位置的白子版本
+```
+
+> 共需 9 种位置 × 3 种状态 = 27 张图（若四角合并可减少）。
+
+---
+
+## 布局与自适应
+
+- 使用 `bricks.Filler` 包裹棋盘以监听 DOM 尺寸变化。
+- `resize_area()` 方法确保棋盘始终居中并等比缩放。
+- 所有点位统一设为正方形，避免拉伸失真。
+- 支持响应式设计，在不同屏幕尺寸下正常显示。
+
+---
+
+## 使用示例
+
+```js
+// 创建五子棋组件并插入页面
+var gobang = new bricks.Gobang({});
+document.body.appendChild(gobang.dom_element);
+
+// （可选）手动更改某个点状态
+var point = gobang.area[7][7]; // 中心点
+point.p_status = 1;
+point.set_url(point.calc_url()); // 重新计算图像
+```
+
+> 若需集成 AI 对战，请扩展 `inform_go` 方法以调用远程服务或本地模型。
+
+---
+
+## 注册与框架集成
+
+```js
+bricks.Factory.register('Gobang', bricks.Gobang);
+```
+
+允许通过工厂模式动态创建实例：
+
+```js
+var game = bricks.Factory.create('Gobang', {});
+```
+
+---
+
+## 待完善功能（TODO）
+
+- ✅ 棋盘渲染与自适应
+- ✅ 棋子状态切换
+- ⬜ 落子逻辑检测（是否已占用）
+- ⬜ 胜负判断（五连珠算法）
+- ⬜ 回合控制与玩家切换
+- ⬜ AI 对手集成（LLM 或规则引擎）
+- ⬜ 悔棋、重新开始等功能按钮
+
+---
+
+## 版权与许可
+
+© 2025 bricks.js 项目组  
+本模块遵循 MIT 许可协议，欢迎自由使用与修改。
\ No newline at end of file
diff --git a/aidocs/html.md b/aidocs/html.md
new file mode 100644
index 0000000..b778719
--- /dev/null
+++ b/aidocs/html.md
@@ -0,0 +1,123 @@
+# `bricks.Html` 组件技术文档
+
+## 概述
+
+`bricks.Html` 是 Bricks 框架中的一个基础 UI 组件，用于将原始 HTML 内容动态插入到 DOM 中。它继承自 `bricks.JsWidget`，是构建更复杂组件或直接渲染静态/动态 HTML 内容的轻量级工具。
+
+---
+
+## 类定义
+
+```javascript
+bricks.Html = class extends bricks.JsWidget
+```
+
+- **继承自**: `bricks.JsWidget`
+- **用途**: 渲染传入的 HTML 字符串到组件的根 DOM 元素中。
+- **注册名称**: `'Html'`（通过 `bricks.Factory` 注册）
+
+---
+
+## 构造函数
+
+### `constructor(opts)`
+
+初始化 `Html` 组件实例。
+
+#### 参数
+
+| 参数名 | 类型   | 说明 |
+|--------|--------|------|
+| `opts` | Object | 配置选项对象，继承自 `JsWidget` 并扩展以下字段。 |
+
+#### `opts` 属性
+
+| 属性名 | 类型   | 必填 | 说明 |
+|--------|--------|------|------|
+| `html` | String | 是   | 要插入到组件内部的 HTML 字符串内容。该内容将直接设置为 `innerHTML`。 |
+
+#### 示例
+
+```javascript
+const htmlWidget = new bricks.Html({
+  html: '<div class="info">这是一段 <strong>HTML</strong> 内容</div>'
+});
+```
+
+---
+
+## 功能说明
+
+- 在构造函数中调用 `super(opts)` 初始化父类 `JsWidget` 的基本功能（如 DOM 创建、事件绑定等）。
+- 使用 `this.dom_element.innerHTML = opts.html` 将传入的 HTML 字符串注入组件的根元素。
+
+> ⚠️ **安全提示**：由于使用了 `innerHTML`，若 `html` 字段包含用户输入，可能存在 XSS 安全风险。建议在使用前对 HTML 内容进行过滤或转义。
+
+---
+
+## 工厂注册
+
+```javascript
+bricks.Factory.register('Html', bricks.Html);
+```
+
+- 将 `Html` 组件注册到 Bricks 的工厂系统中，允许通过配置方式（如 JSON 描述）创建该组件。
+- 注册名称为 `'Html'`，可在模板或布局定义中使用。
+
+#### 工厂创建示例（假设支持 JSON 配置）
+
+```json
+{
+  "type": "Html",
+  "html": "<p>通过工厂创建的 HTML 组件</p>"
+}
+```
+
+---
+
+## 使用示例
+
+### 基本用法
+
+```javascript
+// 创建一个包含 HTML 内容的组件
+const myHtmlComponent = new bricks.Html({
+  html: `
+    <h3>欢迎使用 Bricks Html 组件</h3>
+    <ul>
+      <li>支持任意合法 HTML</li>
+      <li>可嵌入富文本内容</li>
+    </ul>
+  `
+});
+
+// 将组件添加到页面某容器中
+document.getElementById('container').appendChild(myHtmlComponent.dom_element);
+```
+
+---
+
+## 注意事项
+
+1. **安全性**：避免将不可信的用户输入直接赋值给 `html` 字段。
+2. **脚本执行**：通过 `innerHTML` 插入的 `<script>` 标签默认不会执行，如需执行需额外处理。
+3. **样式隔离**：插入的内容会继承父级样式，建议使用 CSS 类名控制样式作用域。
+
+---
+
+## 相关类
+
+- [`bricks.JsWidget`](./JsWidget.md) —— 所有 JavaScript 组件的基类。
+- [`bricks.Factory`](./Factory.md) —— 组件工厂，用于注册和实例化组件。
+
+---
+
+## 版本信息
+
+- **框架**: Bricks UI Framework
+- **模块**: `bricks.Html`
+- **最后更新**: _可根据实际项目填写_
+
+--- 
+
+✅ 适用于快速渲染静态 HTML 内容场景，是构建富文本展示、帮助文档、动态提示等模块的理想选择。
\ No newline at end of file
diff --git a/aidocs/i18n.md b/aidocs/i18n.md
new file mode 100644
index 0000000..a77587a
--- /dev/null
+++ b/aidocs/i18n.md
@@ -0,0 +1,283 @@
+下面是为提供的 JavaScript 代码编写的 **Markdown 格式技术文档**，包含类的功能说明、构造函数参数、方法详解以及使用示例。
+
+---
+
+# `bricks.I18n` 国际化支持类
+
+`bricks.I18n` 是一个轻量级的国际化（i18n）工具类，用于在前端应用中实现多语言文本翻译和动态语言切换。它支持从远程 URL 加载语言包，并缓存已加载的语言资源以提高性能。
+
+该类依赖于全局对象 `window.bricks`，并使用 `bricks.HttpJson` 进行异步请求，同时假设存在辅助函数 `objget` 和 `obj_fmtstr` 用于对象操作和字符串格式化。
+
+---
+
+## 基本结构
+
+```javascript
+var bricks = window.bricks || {};
+bricks.I18n = class {
+    // 实现见下文
+};
+```
+
+> ⚠️ 注意：此代码片段中存在一处变量名错误（`opts` 未定义），已在文档中指出并修正。
+
+---
+
+## 构造函数
+
+### `new bricks.I18n(options)`
+
+初始化 I18n 实例，配置语言资源路径与默认行为。
+
+#### 参数
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `url` | `string` | 否 | 获取语言包的 API 地址（如 `/api/i18n`）。若不提供，则仅支持手动设置字典。 |
+| `method` | `string` | 否 | 请求语言包时使用的 HTTP 方法，默认为 `'GET'`。 |
+| `default_lang` | `string` | 否 | 默认语言代码（如 `'en'`, `'zh-CN'`），默认值为 `'en'`。 |
+
+#### 示例
+
+```js
+const i18n = new bricks.I18n({
+    url: '/api/translations',
+    default_lang: 'zh-CN'
+});
+```
+
+> ❌ **注意原始代码 Bug**：
+> 原始代码中使用了未定义的 `opts` 变量：
+> ```js
+> this.url = opts.url;
+> ```
+> 应改为传入的构造函数参数 `url`, `method`, `default_lang`。**正确实现应如下：**
+
+```js
+constructor(url, default_lang, method) {
+    this.url = url;
+    this.default_lang = default_lang || 'en';
+    this.method = method || 'GET';
+    this.lang_msgs = {}; // 缓存所有语言的消息字典
+    this.msgs = {};      // 当前激活语言的翻译映射
+}
+```
+
+或者接受一个选项对象：
+
+```js
+constructor(options) {
+    this.url = options.url;
+    this.default_lang = options.default_lang || 'en';
+    this.method = options.method || 'GET';
+    this.lang_msgs = {};
+    this.msgs = {};
+}
+```
+
+> ✅ 文档后续基于 **修正后的构造函数** 进行描述。
+
+---
+
+## 方法
+
+### `_ (txt, obj) → string`
+
+获取指定键的翻译文本，并可选地进行变量替换。
+
+#### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `txt` | `string` | 要翻译的键名（key）。 |
+| `obj` | `Object` 或 `undefined` | 用于填充模板字符串的变量对象。 |
+
+#### 返回值
+
+- 如果当前语言中有对应的翻译，返回翻译后的内容；
+- 若提供了 `obj`，则调用 `obj_fmtstr(obj, translatedStr)` 对结果进行格式化；
+- 否则返回原始 `txt`。
+
+#### 示例
+
+```js
+i18n.setup_dict({
+    "hello": "Hello, {name}!",
+    "welcome": "Welcome aboard."
+}, 'en');
+
+i18n._("hello", {name: "Alice"}); 
+// 输出: "Hello, Alice!"
+
+i18n._("welcome");
+// 输出: "Welcome aboard."
+```
+
+---
+
+### `is_loaded(lang) → boolean`
+
+检查某个语言包是否已被加载到内存中。
+
+#### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `lang` | `string` | 语言代码（如 `'zh-CN'`）。 |
+
+#### 返回值
+
+- `true`：该语言的消息字典已加载；
+- `false`：尚未加载。
+
+#### 示例
+
+```js
+if (!i18n.is_loaded('fr')) {
+    await i18n.change_lang('fr');
+}
+```
+
+---
+
+### `setup_dict(dic, lang)`
+
+将给定的语言字典注册到实例中，并立即激活该语言。
+
+> 此方法通常由 `change_lang` 内部调用，也可用于预加载或静态注入语言包。
+
+#### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `dic` | `Object` | 键值对形式的语言翻译表，例如 `{ "ok": "确定" }`。 |
+| `lang` | `string` | 该字典对应的语言代码。 |
+
+#### 行为
+
+- 将 `dic` 存储至 `this.lang_msgs[lang]` 中；
+- 设置 `this.msgs = dic`，即当前活跃语言为 `lang`。
+
+#### 示例
+
+```js
+i18n.setup_dict({
+    "title": "应用标题",
+    "save": "保存"
+}, 'zh-CN');
+```
+
+---
+
+### `async change_lang(lang) → Promise<void>`
+
+切换当前语言环境。如果目标语言未加载，会自动通过网络请求获取。
+
+#### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `lang` | `string` | 目标语言代码（如 `'es'`, `'ja'`）。 |
+
+#### 流程
+
+1. 检查是否已加载该语言：
+   - 是 → 直接激活；
+   - 否 → 发起 HTTP 请求获取语言包。
+2. 使用 `bricks.HttpJson` 发送请求，携带参数 `{ lang }`。
+3. 成功响应后，调用 `setup_dict` 注册并激活新语言。
+
+#### 异常处理
+
+- 若未设置 `this.url`，则跳过请求，无法加载新语言。
+- 错误需由 `HttpJson` 层自行抛出或捕获。
+
+#### 示例
+
+```js
+await i18n.change_lang('zh-CN');
+document.title = i18n._('app_title'); // 使用新语言更新界面
+```
+
+---
+
+## 依赖说明
+
+本类依赖以下外部模块或函数：
+
+| 名称 | 说明 |
+|------|------|
+| `bricks.HttpJson` | 用于发送 JSON 格式的 HTTP 请求，需具备 `httpcall(url, config)` 方法。 |
+| `objget(obj, path)` | 工具函数，安全访问嵌套对象属性（类似 lodash.get）。 |
+| `obj_fmtstr(obj, str)` | 字符串模板替换函数，支持 `{key}` 语法，用 `obj.key` 替换。 |
+
+> 示例 `obj_fmtstr` 实现：
+> ```js
+> function obj_fmtstr(obj, str) {
+>     return str.replace(/\{([^}]+)\}/g, (m, key) => obj[key] || m);
+> }
+> ```
+
+---
+
+## 使用场景示例
+
+### 初始化与语言切换
+
+```js
+// 初始化 i18n 实例
+const i18n = new bricks.I18n({
+    url: '/api/translations',
+    default_lang: 'en'
+});
+
+// 切换语言
+async function setLanguage(lang) {
+    await i18n.change_lang(lang);
+    updateUI(); // 重新渲染页面文本
+}
+
+function updateUI() {
+    document.getElementById('greeting').textContent = i18n._('welcome', { user: 'Tom' });
+}
+```
+
+### 预加载语言包（离线模式）
+
+```js
+// 手动注入英文包
+i18n.setup_dict({
+    "welcome": "Welcome!",
+    "goodbye": "Goodbye!"
+}, 'en');
+
+// 不发起请求，直接切换
+i18n.change_lang('en').then(updateUI);
+```
+
+---
+
+## 注意事项
+
+1. ✅ **修复建议**：原始代码中的 `opts` 应为构造函数参数对象，请确保传参方式一致。
+2. 🔐 安全性：确保服务端返回的语言包内容经过清洗，防止 XSS。
+3. 🌐 性能优化：所有语言包会被缓存，避免重复请求。
+4. ⏱ 异步加载：首次切换未加载语言时需要等待网络响应，请添加加载状态提示。
+
+---
+
+## 版本历史（示例）
+
+| 版本 | 修改内容 |
+|------|----------|
+| 0.1 | 初始版本，支持基本翻译与远程加载 |
+
+---
+
+## 许可证
+
+MIT License
+
+--- 
+
+✅ *文档结束*
\ No newline at end of file
diff --git a/aidocs/iconbarpage.md b/aidocs/iconbarpage.md
new file mode 100644
index 0000000..68461b5
--- /dev/null
+++ b/aidocs/iconbarpage.md
@@ -0,0 +1,218 @@
+# `IconbarPage` 技术文档
+
+> **模块路径**: `bricks.IconbarPage`  
+> **继承自**: `bricks.VBox`  
+> **用途**: 提供一个带有图标工具栏的页面容器，支持顶部或底部布局，并可动态加载内容组件。
+
+---
+
+## 概述
+
+`bricks.IconbarPage` 是一个基于 `bricks.VBox` 的复合组件，用于构建具有图标文本工具栏（`IconTextBar`）和内容区域的页面。工具栏可置于页面顶部或底部，点击工具项时会触发对应的内容展示逻辑。
+
+该组件适用于需要导航式界面的应用场景，如设置页、功能面板或多标签界面。
+
+---
+
+## 类定义
+
+```javascript
+bricks.IconbarPage = class extends bricks.VBox { ... }
+```
+
+---
+
+## 构造函数
+
+### `constructor(opts)`
+
+初始化 `IconbarPage` 实例。
+
+#### 参数
+
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `opts` | Object | 配置选项对象 |
+
+##### `opts` 结构
+
+| 属性 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `bar_opts` | Object | 是 | - | 图标工具栏的配置选项，传递给 `bricks.IconTextBar` |
+| `bar_at` | String | 否 | `'top'` | 工具栏位置，可选 `'top'` 或 `'bottom'` |
+| `height` | String | 否 | `'100%'` | 自动设置为 100%，确保占满父容器高度 |
+
+##### `bar_opts` 子属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `margin` | Number/String | 工具栏外边距 |
+| `rate` | Number | 布局占比（在 VBox 中使用的伸缩比例） |
+| `tools` | Array\<Tool\> | 工具项列表，每个工具项定义一个可点击的操作 |
+
+##### `tools` 数组中的 `tool` 对象结构
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | String | 是 | 工具名称，作为唯一标识 |
+| `icon` | String | 是 | 图标类名（如 Font Awesome 类名） |
+| `label` | String | 否 | 显示文本（可选） |
+| `tip` | String | 是 | 鼠标悬停提示文本 |
+| `dynsize` | Boolean | 否 | 是否动态调整大小 |
+| `rate` | Number | 否 | 在布局中所占比例 |
+| `context` | Object | 否 | 附加上下文数据，可用于命令处理 |
+| `content` | WidgetConfig / Function / Promise | 是 | 要加载的内容组件配置或异步构造逻辑 |
+
+---
+
+## 成员属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `bar_at` | String | 存储工具栏位置（`'top'` 或 `'bottom'`） |
+| `content` | `bricks.Filler` | 内容容器，用于动态插入当前选中的工具对应的内容组件 |
+| `bar` | `bricks.IconTextBar` | 创建的图标文本工具栏实例 |
+
+---
+
+## 方法
+
+### `command_handle(event) → Promise<void>`
+
+处理来自工具栏的命令事件（例如点击某个工具按钮），并加载对应的内容。
+
+#### 参数
+
+- `event`: 事件对象
+  - `params`: 触发事件的 `tool` 对象（即被点击的工具项）
+
+#### 行为
+
+1. 获取触发事件的 `tool`
+2. 调用 `show_content(tool)` 异步加载内容
+
+> ⚠️ 使用 `bind(this)` 绑定上下文，在构造时通过 `bar.bind('command', ...)` 注册。
+
+---
+
+### `show_content(tool) → Promise<void>`
+
+根据传入的 `tool` 动态创建并显示其对应的内容组件。
+
+#### 参数
+
+- `tool`: 工具项对象（包含 `content` 字段）
+
+#### 流程
+
+1. 使用 `bricks.widgetBuild(tool.content, this)` 异步生成组件实例
+2. 若组件存在且尚未添加到 DOM 树，则将其加入 `this.content` 容器
+3. 替换当前内容区域的内容（旧内容会被自动移除？取决于 `Filler` 实现）
+
+> ✅ 支持异步组件加载，适合懒加载或远程模块。
+
+---
+
+## 生命周期与初始化行为
+
+1. 设置默认高度为 `'100%'`
+2. 确定工具栏位置（默认为 `'top'`）
+3. 调用父类 `super(opts)` 初始化 VBox 布局
+4. 创建 `IconTextBar` 实例并传入 `bar_opts`
+5. 创建 `Filler` 作为内容占位符
+6. 根据 `bar_at` 决定工具栏与内容的排列顺序：
+   - `'top'`: 先工具栏，后内容
+   - `'bottom'`: 先内容，后工具栏
+7. 绑定 `command` 事件监听器到 `command_handle`
+8. 使用 `schedule_once` 延迟 0.1 秒自动显示第一个工具项的内容
+
+> 🕒 `schedule_once(..., 0.1)` 可避免渲染冲突，确保 DOM 就绪后再加载初始内容。
+
+---
+
+## 示例用法
+
+```javascript
+var page = new bricks.IconbarPage({
+    bar_at: 'top',
+    bar_opts: {
+        margin: 5,
+        rate: 0,
+        tools: [
+            {
+                name: 'dashboard',
+                icon: 'fa fa-tachometer',
+                label: '仪表盘',
+                tip: '查看系统状态',
+                rate: 1,
+                content: { type: 'DashboardWidget', opts: {} }
+            },
+            {
+                name: 'settings',
+                icon: 'fa fa-cog',
+                tip: '系统设置',
+                content: async function() {
+                    let mod = await import('./SettingsPanel.js');
+                    return new mod.SettingsPanel();
+                }
+            }
+        ]
+    }
+});
+
+document.body.appendChild(page.root);
+```
+
+---
+
+## 事件机制
+
+- **事件类型**: `command`
+- **触发源**: `bricks.IconTextBar`
+- **携带参数**: `event.params` 包含完整的 `tool` 对象
+- **监听方式**: 在 `IconTextBar` 上绑定 `command` 事件
+
+---
+
+## 注册信息
+
+```javascript
+bricks.Factory.register('IconbarPage', bricks.IconbarPage);
+```
+
+可通过工厂方法创建：
+
+```javascript
+bricks.Factory.create('IconbarPage', {...opts});
+```
+
+---
+
+## 注意事项
+
+1. **内容清理**：当前实现未显式清除旧内容，依赖 `Filler` 组件的行为。若需手动管理，请扩展 `show_content` 方法。
+2. **性能优化**：首次加载延迟 0.1s，建议确认是否必要；可考虑使用 `requestAnimationFrame` 或更精确的时机控制。
+3. **错误处理**：`widgetBuild` 失败时无异常捕获，建议包裹 `try-catch` 增强健壮性。
+
+---
+
+## 依赖组件
+
+- `bricks.VBox` —— 垂直布局容器
+- `bricks.IconTextBar` —— 图标+文本工具栏
+- `bricks.Filler` —— 内容填充容器
+- `bricks.widgetBuild` —— 异步构建组件的工具函数
+- `schedule_once` —— 延迟执行工具函数（通常为 `setTimeout` 封装）
+
+---
+
+## 版本历史
+
+| 日期 | 修改人 | 说明 |
+|------|--------|------|
+| 2025-04-05 | AutoDoc Generator | 根据源码生成技术文档 |
+
+--- 
+
+✅ **文档完成**  
+📌 推荐配合 `IconTextBar` 文档一起阅读以理解完整交互逻辑。
\ No newline at end of file
diff --git a/aidocs/iframe.md b/aidocs/iframe.md
new file mode 100644
index 0000000..76071a4
--- /dev/null
+++ b/aidocs/iframe.md
@@ -0,0 +1,184 @@
+# Bricks 框架：Iframe 与 NewWindow 组件技术文档
+
+> **版本**：1.0  
+> **作者**：Bricks 团队  
+> **适用框架**：Bricks.js（基于类的前端组件架构）
+
+---
+
+## 概述
+
+本文档描述 `bricks` 命名空间下的两个核心组件：
+
+- `bricks.Iframe`：用于在当前页面嵌入外部网页内容的 `<iframe>` 组件。
+- `bricks.NewWindow`：用于打开新浏览器窗口并加载指定 URL 的组件。
+
+这两个组件均继承自 `bricks` 框架的基础类，并通过 `bricks.Factory` 注册，支持动态实例化。
+
+---
+
+## 依赖说明
+
+- 需确保全局存在 `window.bricks` 对象（或自动初始化）。
+- 依赖基础类：
+  - `bricks.Layout`：用于 `Iframe`
+  - `bricks.JsWidget`：用于 `NewWindow`
+- 工厂模式注册依赖：`bricks.Factory.register`
+
+---
+
+## 1. `bricks.Iframe` 类
+
+### 继承关系
+```js
+class Iframe extends bricks.Layout
+```
+
+### 功能说明
+创建一个内联框架（`<iframe>`），将指定 URL 的内容嵌入当前页面。默认高度为 `100%`，可自定义。
+
+### 构造函数
+```js
+constructor(opts)
+```
+
+#### 参数
+| 参数 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `opts.url` | `String` | ✅ | 要嵌入的网页 URL |
+| `opts.height` | `String` | ❌ | iframe 高度（默认 `'100%'`） |
+| `opts` 中其他属性 | — | — | 将传递给父类 `bricks.Layout` |
+
+#### 示例
+```js
+const iframe = new bricks.Iframe({
+  url: 'https://example.com',
+  height: '500px'
+});
+```
+
+### 方法
+
+#### `create()`
+创建 DOM 元素 `<iframe>` 并赋值给 `this.dom_element`。
+
+```js
+create()
+```
+
+- **行为**：
+  - 创建一个新的 `HTMLIFrameElement`。
+  - 不自动添加到 DOM，需由父类或外部逻辑处理挂载。
+
+---
+
+## 2. `bricks.NewWindow` 类
+
+### 继承关系
+```js
+class NewWindow extends bricks.JsWidget
+```
+
+### 功能说明
+调用浏览器原生 `window.open()` 方法，在新窗口或标签页中打开指定 URL。
+
+### 构造函数
+```js
+constructor(opts)
+```
+
+#### 参数
+| 参数 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `opts.url` | `String` | ✅ | 要打开的网页地址 |
+| `opts.name` | `String` | ❌ | 新窗口名称（参见 `window.open` 第二参数），默认 `'_blank'` |
+| `opts` 中其他属性 | — | — | 传递给父类 `bricks.JsWidget` |
+
+#### 示例
+```js
+new bricks.NewWindow({
+  url: 'https://example.com',
+  name: 'myWindow'
+});
+// 打开新窗口，名称为 'myWindow'
+
+new bricks.NewWindow({
+  url: 'https://help.com'
+});
+// 使用默认设置打开新标签页
+```
+
+> ⚠️ 注意：现代浏览器可能阻止未用户触发的 `window.open()` 调用（如非点击事件中执行）。
+
+---
+
+## 3. 工厂注册
+
+为支持动态创建组件，两个类均已注册到 `bricks.Factory`。
+
+```js
+bricks.Factory.register('NewWindow', bricks.NewWindow);
+bricks.Factory.register('Iframe', bricks.Iframe);
+```
+
+### 使用工厂创建实例（示例）
+```js
+const widget = bricks.Factory.create('Iframe', {
+  url: 'https://dashboard.example.com',
+  height: '600px'
+});
+document.body.appendChild(widget.getElement()); // 假设方法存在
+```
+
+---
+
+## 使用场景建议
+
+| 组件 | 推荐场景 |
+|------|----------|
+| `Iframe` | 嵌入第三方仪表盘、帮助文档、跨域内容等需要隔离但显示在当前页的内容 |
+| `NewWindow` | 跳转外部链接、打开帮助中心、弹出独立操作界面等无需嵌入当前页面的操作 |
+
+---
+
+## 注意事项
+
+1. **安全性**：
+   - 使用 `<iframe>` 时注意 XSS 和点击劫持风险，建议对源站点设置 CSP 策略。
+   - 避免在 `iframe` 中加载不可信来源。
+
+2. **兼容性**：
+   - `window.open()` 受浏览器弹窗拦截机制影响，请确保在用户交互上下文中调用。
+
+3. **响应式设计**：
+   - `Iframe` 默认高度为 `100%`，请确保其容器具有明确高度，否则可能无法正确渲染。
+
+4. **SEO 与可访问性**：
+   - `<iframe>` 内容不被搜索引擎直接索引，重要信息应避免仅通过 iframe 展示。
+   - 添加 `title` 属性以提升可访问性（当前代码未实现，建议扩展）。
+
+---
+
+## 扩展建议
+
+```js
+// 示例：增强 Iframe 支持 title 和 sandbox 属性
+class EnhancedIframe extends bricks.Iframe {
+  constructor(opts) {
+    super(opts);
+    const { title, sandbox } = opts;
+    if (title) this.dom_element.title = title;
+    if (sandbox) this.dom_element.sandbox = sandbox;
+  }
+}
+```
+
+---
+
+## 版本历史
+
+- **v1.0**：初始版本，包含 `Iframe` 和 `NewWindow` 基础实现及工厂注册。
+
+---
+
+> 📌 提示：更多关于 `bricks.Layout`、`bricks.JsWidget` 和 `bricks.Factory` 的细节，请参考主框架文档。
\ No newline at end of file
diff --git a/aidocs/image.md b/aidocs/image.md
new file mode 100644
index 0000000..195fc5a
--- /dev/null
+++ b/aidocs/image.md
@@ -0,0 +1,350 @@
+# `bricks.Image` 及相关图标组件技术文档
+
+> 基于 `bricks.js` 框架的图像与图标类组件实现
+
+---
+
+## 概述
+
+本模块定义了基于 `bricks.JsWidget` 的一系列图像与图标类组件，用于在网页中动态加载、显示和管理图像资源。主要包括：
+
+- `bricks.Image`：基础图像组件
+- `bricks.Icon`：可缩放的图标组件（继承自 `Image`）
+- `bricks.StatedIcon`：支持状态切换的图标组件（继承自 `Icon`）
+- `bricks.BlankIcon`：占位图标组件（无图像内容）
+
+所有组件均通过 `bricks.Factory` 注册，可在配置系统中通过类型名实例化。
+
+---
+
+## 1. `bricks.Image`
+
+### 类定义
+```js
+class extends bricks.JsWidget
+```
+
+### 构造函数
+```js
+constructor(opts)
+```
+
+#### 参数
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `opts` | Object | 配置选项对象 |
+
+##### `opts` 属性
+| 属性 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `url` | String | 否 | 图像的 URL 地址 |
+| `default_url` | String | 否 | 当主 `url` 加载失败时使用的备用图像地址 |
+
+#### 行为
+- 调用父类构造函数。
+- 若传入 `url`，则自动调用 `set_url()` 设置图像源。
+
+---
+
+### 方法
+
+#### `create()`
+创建一个 `<img>` 元素作为组件的 DOM 根节点。
+
+```js
+create()
+```
+
+> **说明**：该方法由框架调用，在初始化时创建 DOM 结构。
+
+---
+
+#### `set_url(url)`
+设置图像的 `src` 属性，并绑定错误处理以支持默认图像。
+
+```js
+set_url(url)
+```
+
+##### 参数
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `url` | String | 图像资源 URL |
+
+##### 行为
+- 将 `this.url` 设为传入值。
+- 如果配置了 `default_url`，则为 `<img>` 绑定 `onerror` 事件处理器，加载失败时自动切换到默认图。
+- 设置 `dom_element.src = url`
+
+---
+
+#### `set_default_url()`
+当图像加载失败时触发，切换至默认图像。
+
+```js
+set_default_url()
+```
+
+##### 行为
+- 移除 `onerror` 监听器，防止重复触发。
+- 将 `src` 设置为 `this.opts.default_url`
+- 输出日志：`console.log('default_url', this.opts.default_url)`
+
+---
+
+#### `base64()`
+将当前图像绘制到 Canvas 并导出为 Base64 编码的 PNG 数据 URL。
+
+```js
+base64()
+```
+
+##### 返回值
+- `{String}` - 图像的 Data URL，格式如：`data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...`
+
+##### 实现逻辑
+1. 创建临时 `<canvas>` 元素。
+2. 获取上下文并设置画布尺寸等于图像实际宽高。
+3. 使用 `drawImage()` 将图像绘制到画布。
+4. 调用 `toDataURL('image/png')` 生成 Base64 字符串。
+5. 返回结果（未去除头部前缀）。
+
+> ⚠️ 注意：此方法依赖图像已完全加载，否则可能绘制空白或异常内容。
+
+---
+
+#### `removeBase64Header(base64String)`
+移除 Base64 字符串中的 MIME 头部信息（例如 `data:image/png;base64,`）。
+
+```js
+removeBase64Header(base64String)
+```
+
+##### 参数
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `base64String` | String | 完整的 Data URL 字符串 |
+
+##### 返回值
+- `{String}` - 纯 Base64 编码内容
+
+##### 示例
+```js
+const clean = removeBase64Header('data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==');
+// → 'R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw=='
+```
+
+---
+
+## 2. `bricks.Icon`
+
+### 类定义
+```js
+class extends bricks.Image
+```
+
+扩展 `Image` 类，提供基于字符单位（`charsize`）的响应式尺寸控制。
+
+---
+
+### 构造函数
+```js
+constructor(opts)
+```
+
+#### 参数
+同 `bricks.Image`，额外支持以下选项：
+
+##### `opts` 扩展属性
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `rate` | Number | `1` | 缩放倍率，相对于 `charsize` |
+| `cwidth` | Number | `1` | 占据的字符宽度数 |
+| `cheight` | Number | `1` | 占据的字符高度数 |
+| `dynsize` | Boolean | `true` | 是否启用动态尺寸调整 |
+
+#### 行为
+- 调用父类构造函数。
+- 自动执行 `options_parse()` 进行配置解析与尺寸设置。
+
+---
+
+### 方法
+
+#### `options_parse()`
+解析配置项并设置图标尺寸及图像源。
+
+```js
+options_parse()
+```
+
+##### 动作
+1. 设置 `rate`（默认为 1）。
+2. 计算样式尺寸：`siz = bricks.app.charsize * rate + 'px'`
+3. 调用 `set_url(this.url)` 重新加载图像（确保尺寸生效后加载）
+4. 设置 `cwidth`, `cheight`, `dynsize`
+5. 调用 `charsize_sizing()` 应用尺寸策略
+
+> ✅ 提示：`charsize_sizing()` 是 `JsWidget` 提供的方法，用于根据字符网格进行布局适配。
+
+---
+
+## 3. `bricks.StatedIcon`
+
+### 类定义
+```js
+class extends bricks.Icon
+```
+
+支持多状态切换的图标组件，常用于表示不同 UI 状态（如开/关、在线/离线等）。
+
+---
+
+### 构造函数
+```js
+constructor(opts)
+```
+
+#### 参数
+| 属性 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `states` | Array<{state: String, url: String}> | 是 | 状态列表，每个状态包含名称和对应图像 URL |
+| `state` | String | 否 | 初始状态名；若未指定，则使用第一个状态 |
+
+#### 示例配置
+```js
+{
+  states: [
+    { state: 'online', url: '/img/online.png' },
+    { state: 'offline', url: '/img/offline.png' }
+  ],
+  state: 'online'
+}
+```
+
+#### 行为
+- 调用父类构造函数。
+- 自动执行 `options_parse()` 初始化状态。
+
+---
+
+### 方法
+
+#### `options_parse()`
+初始化状态机逻辑。
+
+```js
+options_parse()
+```
+
+##### 行为
+- 若未定义 `states` 数组，则直接返回。
+- 若未设置初始 `state`，则设为 `states[0].state`
+- 调用 `set_state(this.state)` 激活初始状态
+
+---
+
+#### `set_state(state)`
+切换当前图标状态，并更新图像。
+
+```js
+set_state(state)
+```
+
+##### 参数
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `state` | String | 要切换到的状态名称 |
+
+##### 行为
+- 更新 `this.state`
+- 遍历 `this.states` 查找匹配项
+- 找到后设置 `this.url = s.url`
+- 调用 `super.options_parse()` 重新应用图像和尺寸
+
+> 💡 支持链式调用与运行时状态变更。
+
+---
+
+## 4. `bricks.BlankIcon`
+
+### 类定义
+```js
+class extends bricks.JsWidget
+```
+
+一个不渲染图像的“空白图标”，仅保留图标布局结构，用作占位符。
+
+---
+
+### 构造函数
+```js
+constructor(opts)
+```
+
+#### 参数
+同 `Icon`，支持：
+- `rate`: 缩放比例
+- `cwidth`, `cheight`: 字符单元占用
+- `dynsize`: 是否动态调整大小
+
+#### 行为
+- 不创建图像元素。
+- 仅调用 `charsize_sizing()` 实现布局占位。
+
+---
+
+## 工厂注册
+
+所有组件均已注册至 `bricks.Factory`，可在模板或配置中通过字符串类型名实例化：
+
+```js
+bricks.Factory.register('Image', bricks.Image);
+bricks.Factory.register('StatedIcon', bricks.StatedIcon);
+bricks.Factory.register('Icon', bricks.Icon);
+bricks.Factory.register('BlankIcon', bricks.BlankIcon);
+```
+
+### 使用示例（假设模板语法）
+```json
+{
+  "type": "Icon",
+  "url": "/icons/save.png",
+  "rate": 1.5,
+  "cwidth": 2,
+  "cheight": 2
+}
+```
+
+---
+
+## 总结
+
+| 组件 | 用途 | 特性 |
+|------|------|------|
+| `Image` | 显示普通图像 | 支持错误 fallback、Base64 导出 |
+| `Icon` | 可缩放图标 | 基于 `charsize` 自适应尺寸 |
+| `StatedIcon` | 多状态图标 | 支持运行时状态切换 |
+| `BlankIcon` | 布局占位符 | 无图像，仅占空间 |
+
+---
+
+## 注意事项
+
+1. **图像跨域问题**：使用 `base64()` 方法时，若图像来自跨域服务器且未开启 CORS，Canvas 将被污染导致无法导出数据。
+2. **异步加载**：`base64()` 应在图像 `load` 事件完成后调用，否则结果不可靠。
+3. **内存泄漏风险**：频繁调用 `base64()` 会创建大量临时 Canvas，建议缓存或节流。
+4. **默认图像防循环**：确保 `default_url` 图像本身有效，避免 `onerror` 死循环。
+
+---
+
+## 版本信息
+
+- 框架：`bricks.js`
+- 模块：`image.js`
+- 最后更新：2025年4月5日
+
+--- 
+
+✅ **建议使用场景**：
+- 图标按钮、状态指示器、用户头像、动态图像预览等需要灵活控制图像行为的 UI 元素。
\ No newline at end of file
diff --git a/aidocs/input.md b/aidocs/input.md
new file mode 100644
index 0000000..90d45f2
--- /dev/null
+++ b/aidocs/input.md
@@ -0,0 +1,621 @@
+# Bricks UI 组件技术文档
+
+> **版本**: 1.0  
+> **作者**: Bricks Framework Team  
+> **描述**: `bricks.UiType` 及其子类构成了一套用于构建表单输入控件的组件体系，支持文本、密码、数字、日期、文件上传、选择框等多种输入类型。所有组件均继承自统一基类 `bricks.UiType`，并可通过工厂模式动态创建。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [核心基类](#核心基类)
+  - [`bricks.UiType`](#bricksuitype)
+  - [`bricks.UiHide`](#bricksuihide)
+- [基础输入控件](#基础输入控件)
+  - [`bricks.UiStr`](#bricksuistr)
+  - [`bricks.UiPassword`](#bricksuipassword)
+  - [`bricks.UiInt`](#bricksuiint)
+  - [`bricks.UiFloat`](#bricksuifloat)
+  - [`bricks.UiTel`](#bricksuitel)
+  - [`bricks.UiEmail`](#bricksuiemail)
+  - [`bricks.UiDate`](#bricksuidate)
+  - [`bricks.UiText`](#bricksuitext)
+  - [`bricks.UiCode`](#bricksuicode)
+- [复合与特殊控件](#复合与特殊控件)
+  - [`bricks.UiCheck`](#bricksuicheck)
+  - [`bricks.UiCheckBox`](#bricksuicheckbox)
+  - [`bricks.UiSearch`](#bricksuisearch)
+- [多媒体输入控件](#多媒体输入控件)
+  - [`bricks.UiFile`](#bricksuifile)
+  - [`bricks.UiImage`](#bricksuiimage)
+  - [`bricks.UiAudio`](#bricksuiaudio)
+  - [`bricks.UiVideo`](#bricksuivideo)
+- [工厂系统](#工厂系统)
+  - [`bricks._Input`](#bricks_input)
+  - [`Input` 工厂实例](#input-工厂实例)
+
+---
+
+## 概述
+
+该模块提供了一个可扩展的 UI 输入组件框架，基于 JavaScript 类和 DOM 封装，实现以下特性：
+
+- 统一接口：所有输入控件都实现了 `getValue()`, `setValue()`, `reset()`, `resultValue()` 等方法。
+- 表单集成：支持通过 `set_formdata(formData)` 方法将值附加到 `FormData` 对象中。
+- 值校验与格式化：通过正则表达式（`pattern`）进行输入过滤。
+- 动态数据加载：如 `UiCode` 和 `UiCheckBox` 支持从 URL 异步加载选项数据。
+- 用户交互事件：支持 `focus`, `blur`, `changed`, `keydown` 等事件绑定。
+- 国际化支持：标签文本使用 `bricks.app.i18n._()` 进行翻译。
+- 多媒体录制支持：图像、音频、视频可通过摄像头/麦克风直接采集。
+
+---
+
+## 核心基类
+
+### `bricks.UiType`
+
+**继承自**: `bricks.Layout`  
+**用途**: 所有输入控件的抽象基类，定义通用行为。
+
+#### 构造函数
+```js
+new bricks.UiType(opts)
+```
+
+| 参数 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `opts.name` | String | 是 | 控件名称（对应表单字段名） |
+| `opts.value` / `opts.defaultvalue` | Any | 否 | 初始值或默认值 |
+| `opts.required` | Boolean | 否 | 是否为必填项 |
+
+#### 属性
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `name` | String | 字段名称 |
+| `value` | Any | 当前值 |
+| `required` | Boolean | 是否必填 |
+| `ctype` | String | 内部类型标识，默认 `'text'` |
+| `dom_element` | HTMLElement | 渲染后的 DOM 元素 |
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `getValue()` → Object | 返回 `{ name: value }`，若存在用户数据则合并返回 |
+| `set_formdata(formData)` | 将当前值添加到 `FormData` 中 |
+| `resultValue()` → Any | 获取实际提交值（子类重写） |
+| `focus()` | 聚焦输入元素 |
+| `reset()` | 重置为初始值 |
+| `setValue(v)` | 设置值并更新 DOM |
+| `set_disabled(f)` | 设置禁用状态 |
+| `set_readonly(f)` | 设置只读状态 |
+| `set_required(f)` | 设置是否必填 |
+
+---
+
+### `bricks.UiHide`
+
+**继承自**: `bricks.UiType`  
+**用途**: 隐藏字段，不显示但可携带数据。
+
+#### 特性
+- `uitype = 'hide'`
+- 自动设置 `display: none` 样式
+
+#### 示例
+```js
+new bricks.UiHide({ name: 'user_id', value: '12345' })
+```
+
+---
+
+## 基础输入控件
+
+### `bricks.UiStr`
+
+**继承自**: `bricks.UiType`  
+**用途**: 单行文本输入框。
+
+#### 支持配置项 (`opts`)
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `align` | String | 文本对齐方式：`left`, `center`, `right` |
+| `length` | Number | 最大字符数（maxlength） |
+| `minlength` | Number | 最小字符数 |
+| `tip` | String | 提示信息（暂未使用） |
+| `width` | String | 宽度（CSS 单位） |
+| `readonly` | Boolean/String | 是否只读 |
+| `required` | Boolean | 是否必填 |
+| `placeholder` | String | 占位符文本（自动国际化） |
+| `css` | String | 自定义 CSS 类名 |
+| `dynsize` | Boolean | 是否启用动态字体适配 |
+| `cfontsize` | Number | 字体缩放比例 |
+
+#### 方法扩展
+- `create()`：创建 `<input type="text">`
+- `check_pattern(value)`：用正则校验输入
+- `set_value_from_input(event)`：输入时触发值更新与事件派发
+- `onfocus/onblur`：焦点处理，添加高亮样式
+
+#### 示例
+```js
+new bricks.UiStr({
+  name: 'username',
+  placeholder: 'Enter your username',
+  required: true,
+  width: '200px'
+})
+```
+
+---
+
+### `bricks.UiPassword`
+
+**继承自**: `bricks.UiStr`  
+**用途**: 密码输入框。
+
+#### 特性
+- `type="password"`
+- `uitype='password'`
+
+#### 示例
+```js
+new bricks.UiPassword({ name: 'password', placeholder: '******' })
+```
+
+---
+
+### `bricks.UiInt`
+
+**继承自**: `bricks.UiStr`  
+**用途**: 整数输入。
+
+#### 特性
+- `type="number"`
+- `textAlign: right`
+- 正则匹配：`\d*`
+- `resultValue()` 返回 `parseInt(value)`
+
+#### 示例
+```js
+new bricks.UiInt({ name: 'age', length: 3 })
+```
+
+---
+
+### `bricks.UiFloat`
+
+**继承自**: `bricks.UiInt`  
+**用途**: 浮点数输入。
+
+#### 特性
+- 正则匹配：`\d*\.?\d+`
+- 支持小数位控制（`dec_len`）
+- 自动设置 `step` 属性以限制精度
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `dec_len` | 2 | 小数位数 |
+
+#### 示例
+```js
+new bricks.UiFloat({ name: 'price', dec_len: 2 })
+```
+
+---
+
+### `bricks.UiTel`
+
+**继承自**: `bricks.UiStr`  
+**用途**: 电话号码输入。
+
+#### 特性
+- `type="tel"`
+- 默认正则：`[+]?\\d+`
+- 支持自定义 `pattern`
+
+#### 示例
+```js
+new bricks.UiTel({ name: 'phone', pattern: '[0-9]{11}' })
+```
+
+---
+
+### `bricks.UiEmail`
+
+**继承自**: `bricks.UiStr`  
+**用途**: 邮箱地址输入。
+
+#### 特性
+- `type="email"`
+- 可选自定义 `pattern`
+
+#### 示例
+```js
+new bricks.UiEmail({ name: 'email', required: true })
+```
+
+---
+
+### `bricks.UiDate`
+
+**继承自**: `bricks.UiStr`  
+**用途**: 日期选择器。
+
+#### 支持配置
+| 属性 | 说明 |
+|------|------|
+| `max_date` | 最大允许日期（字符串格式 YYYY-MM-DD） |
+| `min_date` | 最小允许日期 |
+
+#### 特性
+- `type="date"`
+- 若值为空，`resultValue()` 返回 `null`
+
+#### 示例
+```js
+new bricks.UiDate({
+  name: 'birth_date',
+  min_date: '1900-01-01',
+  max_date: '2024-12-31'
+})
+```
+
+---
+
+### `bricks.UiText`
+
+**继承自**: `bricks.UiType`  
+**用途**: 多行文本域（textarea）。
+
+#### 支持配置
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `rows` | Number | 行数 |
+| `cols` | Number | 列数 |
+| `height` | String | 高度（默认 `'200px'`） |
+
+#### 特性
+- 支持 Tab 缩进（每 4 空格）
+- Shift+Tab 删除缩进
+- Enter 换行（阻止默认行为）
+- 支持代码编辑风格缩进逻辑
+
+#### 方法
+| 方法 | 说明 |
+|------|------|
+| `handle_tab_indent(erase)` | 处理 Tab 缩进或反向删除 |
+| `handle_enter()` | 插入换行并保持光标位置 |
+
+#### 示例
+```js
+new bricks.UiText({ name: 'description', rows: 6, cols: 50 })
+```
+
+---
+
+### `bricks.UiCode`
+
+**继承自**: `bricks.UiType`  
+**用途**: 下拉选择框（类似 `<select>`），常用于枚举字段。
+
+#### 支持配置
+| 属性 | 说明 |
+|------|------|
+| `data` | 本地数据数组 `[ { value: '', text: '' } ]` |
+| `dataurl` | 数据源 URL（异步加载） |
+| `params` | 请求参数 |
+| `method` | HTTP 方法（GET/POST） |
+| `valueField` | 值字段名（默认 `'value'`） |
+| `textField` | 显示文本字段名（默认 `'text'`） |
+| `nullable` | 是否允许空选项 |
+
+#### 特性
+- 支持动态加载数据（`load_data()`）
+- 支持级联刷新（通过 `get_data(event)` 接收上级事件参数）
+- 自动生成 `<option>` 元素
+- 支持国际化文本显示
+
+#### 方法
+| 方法 | 说明 |
+|------|------|
+| `build_options(data)` | 构建下拉选项 |
+| `load_data(params)` | 异步获取数据 |
+| `get_data(event?)` | 触发数据加载（可带参数） |
+
+#### 示例
+```js
+new bricks.UiCode({
+  name: 'status',
+  dataurl: '/api/statuses',
+  textField: 'label',
+  valueField: 'id'
+})
+```
+
+---
+
+## 复合与特殊控件
+
+### `bricks.UiCheck`
+
+**继承自**: `bricks.UiType`  
+**用途**: 单个复选图标（SVG 图标切换）。
+
+#### 特性
+- 使用 `MultipleStateIcon` 显示 checked/unchecked 状态
+- 图标资源路径：
+  - checked: `imgs/checkbox-checked.svg`
+  - unchecked: `imgs/checkbox-unchecked.svg`
+- 值为布尔类型
+
+#### 方法
+| 方法 | 说明 |
+|------|------|
+| `setValue(true/false)` | 设置状态 |
+| `set_value_from_input()` | 响应图标点击，派发 `changed` 事件 |
+
+#### 示例
+```js
+new bricks.UiCheck({ name: 'agree', value: false })
+```
+
+---
+
+### `bricks.UiCheckBox`
+
+**继承自**: `bricks.UiType`  
+**用途**: 多选或单选组（fieldset + legend + 多个 UiCheck）。
+
+#### 支持配置
+| 属性 | 说明 |
+|------|------|
+| `data` | 选项列表 `[ { value: '', text: '' } ]` |
+| `dataurl` | 异步数据源 |
+| `textField` | 显示字段 |
+| `valueField` | 值字段 |
+| `label` | 分组标题（legend） |
+
+#### 特性
+- 支持多选（数组）和单选（字符串）
+- 动态构建多个 `UiCheck` 实例
+- 支持异步加载数据（`load_data_onfly()`）
+
+#### 方法
+| 方法 | 说明 |
+|------|------|
+| `build_checkboxs()` | 根据数据生成复选框列表 |
+| `set_value_from_input()` | 更新选中值并广播 `changed` 事件 |
+| `setValue(v)` | 设置选中项（支持数组或单值） |
+
+#### 示例
+```js
+new bricks.UiCheckBox({
+  name: 'hobbies',
+  label: 'Your Hobbies',
+  data: [
+    { value: 'reading', text: 'Reading' },
+    { value: 'music', text: 'Music' }
+  ],
+  multicheck: true
+})
+```
+
+---
+
+### `bricks.UiSearch`
+
+**继承自**: `bricks.HBox`  
+**用途**: 搜索选择器，点击图标弹出窗口选择数据。
+
+#### 支持配置
+| 属性 | 说明 |
+|------|------|
+| `search_url` | 弹窗内容页面 URL |
+| `valueField` | 返回值字段 |
+| `textField` | 显示字段 |
+| `popup_options` | 弹窗配置 |
+| `text` | 显示文本（非值） |
+
+#### 特性
+- 包含一个只读 `UiStr` 和一个搜索图标（SVG）
+- 点击图标打开弹窗（`default_popupwindow`）
+- 弹窗内查找 `Tabular` 组件并绑定事件
+- 选择后调用 `set_data()` 更新值
+
+#### 方法
+| 方法 | 说明 |
+|------|------|
+| `open_search_window()` | 打开搜索弹窗 |
+| `set_data(event)` | 接收选择结果并填充 |
+
+#### 示例
+```js
+new bricks.UiSearch({
+  name: 'customer_id',
+  search_url: '/pages/customer_picker.html',
+  valueField: 'id',
+  textField: 'name'
+})
+```
+
+---
+
+## 多媒体输入控件
+
+### `bricks.UiFile`
+
+**继承自**: `bricks.VBox`  
+**用途**: 文件上传控件，支持拖拽和点击选择。
+
+#### 支持配置
+| 属性 | 说明 |
+|------|------|
+| `accept` | MIME 类型过滤（如 `'image/'`, `'audio/'`） |
+| `multiple` | 是否允许多选 |
+
+#### 特性
+- 支持拖拽上传
+- 自动监听 `dragover`, `drop` 等事件
+- 内部包含隐藏 `<input type="file">`
+- 支持 `set_input_file(files)` 手动设置文件列表
+
+#### 方法
+| 方法 | 说明 |
+|------|------|
+| `handleFileSelect()` | 处理文件选择 |
+| `dropHandle()` | 处理拖放事件 |
+| `resultValue()` | 返回 File 或 FileList |
+
+#### 示例
+```js
+new bricks.UiFile({ name: 'attachment', accept: 'application/pdf', multiple: true })
+```
+
+---
+
+### `bricks.UiImage`
+
+**继承自**: `bricks.UiFile`  
+**用途**: 图像上传 + 拍照功能。
+
+#### 特性
+- `accept='image/'`
+- 添加拍照按钮（调用 `SysCamera`）
+- 支持预览上传或拍摄的图片（`show_image()`）
+
+#### 方法
+| 方法 | 说明 |
+|------|------|
+| `take_photo()` | 打开相机 |
+| `accept_photo()` | 接收拍摄结果 |
+| `_show_image(file)` | 显示图片预览（URL 或 Blob） |
+
+#### 示例
+```js
+new bricks.UiImage({ name: 'avatar' })
+```
+
+---
+
+### `bricks.UiAudio`
+
+**继承自**: `bricks.UiFile`  
+**用途**: 音频上传 + 录音功能。
+
+#### 特性
+- `accept='audio/'`
+- 添加录音按钮（调用 `SysAudioRecorder`）
+- 支持播放预览（`AudioPlayer`）
+
+#### 方法
+| 方法 | 说明 |
+|------|------|
+| `open_recorder()` | 打开录音器 |
+| `accept_audio()` | 接收录音文件 |
+| `_show_audio(file)` | 显示音频播放器 |
+
+#### 示例
+```js
+new bricks.UiAudio({ name: 'voice_note' })
+```
+
+---
+
+### `bricks.UiVideo`
+
+**继承自**: `bricks.UiFile`  
+**用途**: 视频上传 + 录制功能。
+
+#### 特性
+- `accept='video/'`
+- 添加录像按钮（调用 `SysVideoRecorder`）
+- 支持视频预览（`VideoPlayer`）
+
+#### 方法
+| 方法 | 说明 |
+|------|------|
+| `open_recorder()` | 打开录像器 |
+| `accept_video()` | 接收录像文件 |
+| `_show_video(file)` | 显示视频播放器 |
+
+#### 示例
+```js
+new bricks.UiVideo({ name: 'demo_video' })
+```
+
+---
+
+## 工厂系统
+
+### `bricks._Input`
+
+**用途**: 输入控件工厂类，用于注册和创建 UI 组件。
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `register(name, uitype, Klass)` | 注册组件类 |
+| `factory(options)` | 根据 `uitype` 创建实例 |
+
+#### 示例
+```js
+const factory = new bricks._Input();
+factory.register('UiStr', 'str', bricks.UiStr);
+const input = factory.factory({ uitype: 'str', name: 'title' });
+```
+
+---
+
+### `Input` 工厂实例
+
+全局已初始化的工厂对象，预注册了所有标准控件。
+
+#### 已注册映射表
+
+| 名称 (name) | uitype | 类 |
+|------------|--------|-----|
+| `UiStr` | `str` | `bricks.UiStr` |
+| `UiPassword` | `password` | `bricks.UiPassword` |
+| `UiInt` | `int` | `bricks.UiInt` |
+| `UiFloat` | `float` | `bricks.UiFloat` |
+| `UiTel` | `tel` | `bricks.UiTel` |
+| `UiEmail` | `email` | `bricks.UiEmail` |
+| `UiDate` | `date` | `bricks.UiDate` |
+| `UiText` | `text` | `bricks.UiText` |
+| `UiCode` | `code` | `bricks.UiCode` |
+| `UiCheck` | `check` | `bricks.UiCheck` |
+| `UiCheckBox` | `checkbox` | `bricks.UiCheckBox` |
+| `UiFile` | `file` | `bricks.UiFile` |
+| `UiImage` | `image` | `bricks.UiImage` |
+| `UiAudio` | `audio`, `audiorecorder` | `bricks.UiAudio` |
+| `UiVideo` | `video` | `bricks.UiVideo` |
+| `UiSearch` | `search` | `bricks.UiSearch` |
+| `UiHide` | `hide` | `bricks.UiHide` |
+
+#### 使用方式
+```js
+const field = Input.factory({ uitype: 'email', name: 'contact_email' });
+```
+
+---
+
+## 总结
+
+本组件库提供了完整且可扩展的前端表单输入解决方案，具备以下优势：
+
+✅ 统一 API 接口  
+✅ 支持异步数据加载  
+✅ 多媒体采集支持  
+✅ 可定制样式与行为  
+✅ 支持国际化  
+✅ 事件驱动架构  
+
+适用于构建复杂的表单页面、数据录入系统、移动端 Web 应用等场景。
+
+--- 
+
+> ✅ **提示**：建议结合 `bricks.Layout`、`bricks.HBox`/`VBox` 布局容器组织表单结构。  
+> 📁 **资源路径**：图标资源位于 `imgs/` 目录下，需确保正确部署。
\ No newline at end of file
diff --git a/aidocs/jsoncall.md b/aidocs/jsoncall.md
new file mode 100644
index 0000000..2970dab
--- /dev/null
+++ b/aidocs/jsoncall.md
@@ -0,0 +1,391 @@
+# Bricks HTTP 模块技术文档
+
+本模块为 `bricks` 前端框架提供了一套完整的 HTTP 请求处理工具集，支持多种响应类型（文本、JSON、二进制流等），并封装了自动参数注入、错误处理、会话管理与登录重定向等功能。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [核心功能](#核心功能)
+- [公共函数](#公共函数)
+- [基类：`HttpText`](#基类httptext)
+- [派生类](#派生类)
+  - [`HttpArrayBuffer`](#httparraybuffer)
+  - [`HttpBin`](#httpbin)
+  - [`HttpResponse`](#httpresponse)
+  - [`HttpResponseStream`](#httpresponsestream)
+  - [`HttpRaw`](#httpraw)
+  - [`HttpJson`](#httpjson)
+- [快捷方法](#快捷方法)
+- [使用示例](#使用示例)
+
+---
+
+## 概述
+
+`bricks.Http*` 系列类基于 `fetch` API 构建，旨在统一前端网络请求行为。主要特性包括：
+
+- 自动附加设备信息和会话参数
+- 支持 GET/POST 请求及 FormData 或 JSON 数据格式
+- 统一的错误提示机制（401、403、其他错误）
+- 可扩展的响应处理器（文本、JSON、流式解析等）
+- 登录拦截与跳转支持（待完善）
+
+该模块适用于 Web 应用中需要与后端服务交互的所有场景。
+
+---
+
+## 核心功能
+
+| 功能 | 描述 |
+|------|------|
+| 参数合并 | 自动注入 `_webbricks_`, 屏幕宽高, 移动端标识等参数 |
+| 会话管理 | 从响应头读取 `Set-Cookie` 并保存会话；发送时自动携带 |
+| 错误处理 | 对 401、403 和非 OK 状态码进行统一 UI 提示 |
+| 登录重定向 | 当返回 401 且存在 `login_url` 时触发登录流程（目前未完全实现） |
+| 流式响应处理 | 支持逐行处理 chunked 响应数据（如 Server-Sent Events） |
+
+---
+
+## 公共函数
+
+### `url_params(data)`
+
+将对象转换为 URL 查询字符串。
+
+#### 参数
+- `data`: `{[key: string]: any}` — 要编码的对象
+
+#### 返回值
+- `string` — 格式化后的查询字符串（例如 `"a=1&b=2"`）
+
+#### 示例
+```js
+url_params({a: 1, b: 'hello'}) // → "a=1&b=hello"
+```
+
+> ⚠️ 所有值都会通过 `encodeURIComponent` 编码。
+
+---
+
+## 基类：`HttpText`
+
+所有 HTTP 客户端类的基类。
+
+### 构造函数 `constructor(headers?)`
+
+#### 参数
+- `headers?`: `{[key: string]: string}` — 自定义请求头，默认为 `{ Accept: "text/html" }`
+
+#### 行为说明
+- 若未传入 `headers`，默认使用：
+  ```js
+  { "Accept": "text/html" }
+  ```
+- 使用 `bricks.extend()` 合并默认头与用户头。
+- 自动收集以下上下文参数作为请求参数：
+  - `_webbricks_`: 固定值 `1`
+  - `width`: 屏幕宽度（来自 `bricks.app.screenWidth()`）
+  - `height`: 屏幕高度（来自 `bricks.app.screenHeight()`）
+  - `_is_mobile`: 是否为移动端（`'1'` 或 `'0'`）
+
+> ✅ 这些参数会在每次请求中自动附加。
+
+### 方法
+
+#### `url_parse(url)`
+
+解析 URL 中的查询参数，并将其合并到内部 `this.params` 中。
+
+##### 参数
+- `url`: `string` — 原始 URL（含 query）
+
+##### 返回值
+- `string` — 清除 query 的基础 URL
+
+##### 示例
+```js
+const client = new bricks.HttpText();
+client.url_parse("/api/data?a=1&b=2");
+// 结果：client.params 包含 a=1, b=2
+// 返回 "/api/data"
+```
+
+#### `add_own_params(params)`
+
+合并用户参数与内部参数（包括 session）。
+
+##### 参数
+- `params`: `Object | FormData | null`
+
+##### 返回值
+- `Object | FormData` — 合并后的参数对象
+
+##### 行为逻辑
+- 如果是 `FormData`，直接追加键值对
+- 否则创建新对象，合并 `this.params` 和 `params`
+- 若存在 `bricks.app.get_session()`，额外添加 `session` 字段
+
+#### `add_own_headers(headers)`
+
+合并自定义请求头与实例默认头。
+
+##### 参数
+- `headers`: `{[key: string]: string} | null`
+
+##### 返回值
+- `Object` — 合并后的 headers
+
+> 使用 `Object.assign(this.headers, headers)` 实现浅合并。
+
+#### `async bricks_fetch(url, {method, headers, params})`
+
+底层 `fetch` 封装，负责构建最终请求选项。
+
+##### 参数
+- `url`: `string` — 请求地址
+- `method`: `'GET'|'POST'|'HEAD'|...` — HTTP 方法（默认 `'GET'`）
+- `headers`: `Object` — 请求头
+- `params`: `Object|FormData` — 请求参数
+
+##### 处理逻辑
+| 条件 | 行为 |
+|------|------|
+| `params instanceof FormData` | 强制设为 POST，`body = params` |
+| `GET/HEAD` 请求 | 将 `params` 转为 query string 拼接到 URL |
+| 其他方法（如 POST） | `body = JSON.stringify(params)` |
+
+##### 返回值
+- `Response` — fetch 返回的原生响应对象
+
+#### `async httpcall(url, opts)`
+
+高层封装，包含状态码判断与错误处理。
+
+##### 参数
+- `url`: `string`
+- `opts`: `{method, headers, params}`
+
+##### 流程
+1. 调用 `bricks_fetch` 发起请求
+2. 检查响应状态：
+   - **401** 且配置了 `bricks.app.login_url` → 触发 `withLoginInfo`
+   - **403** → 显示“禁止访问”弹窗
+   - 非 `ok` → 显示通用错误弹窗
+3. 成功则调用 `get_result_data()` 获取结果
+4. 解析 `Set-Cookie` 并调用 `bricks.app.save_session(session)` 保存会话
+
+##### 返回值
+- `string | null` — 成功返回响应内容，失败返回 `null`
+
+#### `async withLoginInfo(url, params)`
+
+处理 401 时尝试重新登录（当前仅为占位实现）。
+
+> ❗ 当前仅创建一个 `urlwidget` 加载登录页，未完成回调或重试逻辑。
+
+#### `async get_result_data(resp)`
+
+提取响应体数据的方法（可被子类覆盖）。
+
+##### 默认实现（`HttpText`）
+```js
+return await resp.text();
+```
+
+---
+
+## 派生类
+
+### `HttpArrayBuffer`
+
+继承自 `HttpText`，用于下载二进制文件（如字体、模型等）。
+
+#### 重写方法
+```js
+async get_result_data(resp) {
+  return await resp.arrayBuffer();
+}
+```
+
+---
+
+### `HttpBin`
+
+继承自 `HttpText`，以 Blob 形式获取响应（适合图片、音频等）。
+
+#### 重写方法
+```js
+async get_result_data(resp) {
+  return await resp.blob();
+}
+```
+
+---
+
+### `HttpResponse`
+
+继承自 `HttpText`，直接返回原始 `Response` 对象。
+
+#### 重写方法
+```js
+async get_result_data(resp) {
+  return resp;
+}
+```
+
+> ✅ 适用于需手动处理 header 或 stream 的高级场景。
+
+---
+
+### `HttpResponseStream`
+
+继承自 `HttpResponse`，专用于处理流式响应（如 SSE）。
+
+#### 方法：`async handle_chunk(resp, handler)`
+
+逐行解析 chunked 文本流，并调用 `handler(line)`。
+
+##### 参数
+- `resp`: `Response` — fetch 返回的响应对象
+- `handler`: `(line: string) => void` — 每一行数据的处理器
+
+##### 实现细节
+- 使用 `ReadableStream.getReader()` + `TextDecoder`
+- 按 `\n` 分割缓冲区，确保跨 chunk 边界正确切分
+- 最终剩余内容也会传递给 `handler`
+
+##### 示例用法
+```js
+const streamClient = new bricks.HttpResponseStream();
+const resp = await streamClient.get('/stream-endpoint');
+await streamClient.handle_chunk(resp, (line) => {
+  console.log('Received:', line);
+});
+```
+
+---
+
+### `HttpRaw`
+
+与 `HttpBin` 相同，返回 `Blob`。
+
+> ⚠️ 注释中可能表示未来用途不同，但当前实现与 `HttpBin` 完全一致。
+
+---
+
+### `HttpJson`
+
+专用于 JSON 接口通信，设置默认 Accept 头并解析 JSON 响应。
+
+#### 构造函数增强
+```js
+this.headers = { "Accept": "application/json" };
+bricks.extend(this.headers, headers); // 用户头可覆盖
+```
+
+#### 重写方法
+```js
+async get_result_data(resp) {
+  return await resp.json();
+}
+```
+
+> ✅ 推荐用于 RESTful API 调用。
+
+---
+
+## 快捷方法
+
+模块末尾导出多个常用快捷函数，绑定到全局命名空间：
+
+| 变量名 | 类型 | 说明 |
+|--------|------|------|
+| `bricks.hc` | `new HttpText()` | 文本客户端实例 |
+| `bricks.tget` | `Function` | `hc.get` 的绑定方法（GET 文本） |
+| `bricks.tpost` | `Function` | `hc.post` 的绑定方法（POST 文本） |
+| `bricks.jc` | `new HttpJson()` | JSON 客户端实例 |
+| `bricks.jcall` | `Function` | `jc.httpcall` 的绑定方法（调用 JSON 接口） |
+| `bricks.jget` | `Function` | `jc.get` 的绑定方法（GET JSON） |
+| `bricks.jpost` | `Function` | `jc.post` 的绑定方法（POST JSON） |
+
+### 示例
+```js
+// 获取 HTML 内容
+const html = await bricks.tget('/page', { params: { id: 123 } });
+
+// 调用 JSON 接口
+const data = await bricks.jpost('/api/user', {
+  headers: { 'X-Token': 'abc' },
+  params: { name: 'Alice' }
+});
+```
+
+---
+
+## 使用示例
+
+### 1. 发送普通 GET 请求
+```js
+const client = new bricks.HttpText();
+const result = await client.get('/api/hello', {
+  params: { q: 'test' }
+});
+console.log(result); // 输出服务器返回的文本
+```
+
+### 2. 发送 JSON POST 请求
+```js
+const jsonClient = new bricks.HttpJson();
+const user = await jsonClient.post('/api/users', {
+  params: { name: 'Bob', age: 30 }
+});
+// 自动设置 Content-Type 和 Accept，并解析 JSON
+```
+
+### 3. 下载文件为 ArrayBuffer
+```js
+const bufferClient = new bricks.HttpArrayBuffer();
+const resp = await bufferClient.get('/model.bin');
+const arrayBuf = await resp; // 已是 arrayBuffer
+```
+
+### 4. 处理实时日志流
+```js
+const streamClient = new bricks.HttpResponseStream();
+const resp = await streamClient.get('/logs/stream');
+await streamClient.handle_chunk(resp, (line) => {
+  console.log('[LOG]', line);
+});
+```
+
+---
+
+## 注意事项
+
+- 依赖 `bricks.app` 提供 `screenWidth()`, `screenHeight()`, `get_session()`, `save_session()` 等方法
+- 依赖 `bricks.extend(obj, src)` 实现对象合并（类似 jQuery.extend）
+- `objget(headers, 'Set-Cookie')` 用于安全获取响应头（需外部定义）
+- 登录流程尚未完整实现，`withLoginInfo` 仅为原型
+
+---
+
+## 待优化建议
+
+| 问题 | 建议改进 |
+|------|---------|
+| `bufffer` 拼写错误 | 修复 `if (buffer != ''){ yield bufffer; }` 中的拼写 |
+| `withLoginInfo` 无实际登录能力 | 应支持模态框输入并回调重试请求 |
+| `handle_chunk` 正则 `/\\r?\\n/gm` 不必要 | 可简化为 `.split('\n')` |
+| `bricks_fetch` 中 `method = 'POST'` 修改外层变量风险 | 应使用局部变量 |
+
+---
+
+## 版本信息
+
+- 创建时间：未知
+- 框架版本：Bricks Framework v1.x+
+- 作者：Bricks Team
+
+> 文档最后更新：2025年4月5日
\ No newline at end of file
diff --git a/aidocs/keypress.md b/aidocs/keypress.md
new file mode 100644
index 0000000..f4a343e
--- /dev/null
+++ b/aidocs/keypress.md
@@ -0,0 +1,126 @@
+# `bricks.KeyPress` 组件技术文档
+
+> 一个用于监听键盘按键并实时显示按键信息的 UI 组件。
+
+---
+
+## 概述
+
+`bricks.KeyPress` 是基于 `bricks.VBox` 的扩展类，用于创建一个能够监听全局键盘事件（`keydown`）的组件。当用户按下任意键时，该组件会清除当前内容，并显示被按下的键名。
+
+此组件常用于调试、快捷键提示或交互式输入反馈场景。
+
+---
+
+## 继承关系
+
+- **继承自**: `bricks.VBox`
+- **类型**: 类（Class）
+- **注册名称**: `'KeyPress'`（通过 `bricks.Factory` 注册）
+
+---
+
+## 构造函数
+
+```js
+constructor(opts)
+```
+
+### 参数
+
+| 参数名 | 类型   | 说明 |
+|--------|--------|------|
+| `opts` | Object | 传递给父类 `VBox` 的配置选项，如布局、样式等。 |
+
+### 行为
+
+1. 调用 `super(opts)` 初始化父类 `VBox`。
+2. 使用 `bricks.app.bind('keydown', ...)` 绑定全局键盘按下事件，将 `this.key_handler` 作为回调函数，并确保其上下文指向当前实例。
+
+---
+
+## 方法
+
+### `key_handler(event)`
+
+处理键盘按下事件的回调函数。
+
+#### 参数
+
+| 参数名  | 类型        | 说明                   |
+|---------|-------------|------------------------|
+| `event` | KeyboardEvent | 浏览器原生键盘事件对象。 |
+
+#### 实现逻辑
+
+1. 获取 `event.key` 字符串表示（例如 `"a"`, `"Enter"`, `"Shift"` 等）。
+2. 如果 `event.key` 不存在，则直接返回，不进行后续操作。
+3. 调用 `this.clear_widgets()` 清除当前容器内的所有子控件。
+4. 创建一个新的 `bricks.Text` 控件，显示文本：`"key press is: <key>"`。
+5. 使用 `this.add_widget(w)` 将新文本控件添加到当前容器中。
+
+#### 示例输出
+
+- 按下字母 A → 显示：`key press is: a`
+- 按下回车键 → 显示：`key press is: Enter`
+- 按下空格键 → 显示：`key press is: `（后面是一个空格）
+
+---
+
+## 工厂注册
+
+```js
+bricks.Factory.register('KeyPress', bricks.KeyPress);
+```
+
+注册后可通过工厂方法动态创建该组件：
+
+```js
+var keyPressWidget = bricks.Factory.create('KeyPress', { /* opts */ });
+```
+
+---
+
+## 使用示例
+
+```js
+// 创建 KeyPress 组件实例
+var keyDisplay = new bricks.KeyPress({
+    style: {
+        padding: '10px',
+        border: '1px solid #ccc'
+    }
+});
+
+// 添加到页面某个容器中
+someContainer.add_widget(keyDisplay);
+```
+
+---
+
+## 注意事项
+
+- 依赖全局对象 `bricks.app` 必须实现 `.bind(eventType, handler)` 方法来绑定 DOM 事件。
+- 仅响应 `keydown` 事件，不处理 `keyup` 或 `keypress`。
+- 每次按键都会清空原有内容，仅保留最新一次按键信息。
+
+---
+
+## 依赖项
+
+- `bricks.VBox` —— 布局容器基类。
+- `bricks.Text` —— 文本显示组件。
+- `bricks.Factory` —— 组件工厂，用于注册和创建组件。
+- `bricks.app` —— 应用级事件管理器。
+
+---
+
+## 版本信息
+
+- **模块**: `bricks`
+- **组件**: `KeyPress`
+- **最后更新**: 请根据实际项目填写
+
+--- 
+
+✅ *可用于开发调试面板、快捷键教学模块等场景。*
\ No newline at end of file
diff --git a/aidocs/layout.md b/aidocs/layout.md
new file mode 100644
index 0000000..be155c4
--- /dev/null
+++ b/aidocs/layout.md
@@ -0,0 +1,359 @@
+# `bricks.Layout` 及其子类技术文档
+
+本技术文档详细描述了 `bricks.Layout` 类及其相关布局组件（如 `VBox`, `HBox`, `Filler`, `ResponsableBox` 等）的功能、结构和使用方式。这些类是基于 `bricks.JsWidget` 构建的 UI 容器组件，支持键盘导航、动态内容管理与响应式布局。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [核心模块](#核心模块)
+  - [`bricks.Layout`](#brickslayout)
+  - [`bricks.VBox`](#bricksvbox)
+  - [`bricks.HBox`](#brickshbox)
+  - [`bricks.FHBox`](#bricksfhbox)
+  - [`bricks.FVBox`](#bricksfvbox)
+  - [`bricks.Filler`](#bricksfiller)
+  - [`bricks.ResponsableBox`](#bricksresponsablebox)
+- [键盘选择机制](#键盘选择机制)
+- [事件处理](#事件处理)
+- [方法说明](#方法说明)
+- [工厂注册](#工厂注册)
+- [示例用法](#示例用法)
+
+---
+
+## 概述
+
+`bricks` 是一个前端 UI 组件框架，`Layout` 是其基础容器类，用于组织和管理子控件（widgets）。所有布局类均继承自 `bricks.Layout`，并可通过 CSS 类实现水平或垂直排列。此外，该系统支持**键盘导航**，允许用户通过方向键在可聚焦元素之间切换，并通过 Enter 键触发操作。
+
+主要特性包括：
+
+- 支持嵌套布局结构
+- 提供标题、描述、工具栏构建方法
+- 内置键盘导航支持（上下左右 + Enter）
+- 基于栈的层级导航机制
+- 动态添加/删除子控件
+- 响应式设计支持（`ResponsableBox`）
+
+---
+
+## 核心模块
+
+### `bricks.Layout`
+
+#### 继承关系
+```js
+class Layout extends bricks.JsWidget
+```
+
+#### 属性
+
+| 属性名 | 类型 | 描述 |
+|-------|------|------|
+| `_container` | Boolean | 标记为容器组件 |
+| `keyselectable` | Boolean | 是否启用键盘选择功能 |
+| `children` | Array | 子控件列表 |
+| `selected_item` | Widget | 当前选中的子控件 |
+| `title` | String (可选) | 容器标题文本 |
+| `description` | String (可选) | 描述文本 |
+| `toolbar` | Object (可选) | 工具栏配置对象 |
+| `use_key_select` | Boolean (可选) | 初始化时是否自动启用键盘选择 |
+
+> ⚠️ 注意：`use_key_select` 在代码中未明确定义于构造函数参数，但被条件判断引用，建议作为选项传入。
+
+#### 构造函数
+```js
+constructor(options)
+```
+- **参数**：
+  - `options` `{Object}` 配置项，支持以下字段：
+    - `title`: 显示标题
+    - `description`: 显示描述
+    - `toolbar`: 工具栏配置
+    - `keyselectable`: 是否允许键盘选择（默认 `false`）
+    - `use_key_select`: 若为真，则自动调用 `enable_key_select()`
+
+- **行为**：
+  - 调用父类构造函数
+  - 初始化内部状态
+  - 若设置了 `use_key_select`，则立即启用键盘选择模式
+
+---
+
+### `bricks.VBox`
+
+垂直布局容器，子元素垂直堆叠。
+
+```js
+class VBox extends Layout
+```
+
+- **构造函数**：
+  - 自动设置 CSS 类：`vcontainer`
+- **用途**：创建纵向排列的内容区域。
+
+---
+
+### `bricks.HBox`
+
+水平布局容器，子元素水平排列。
+
+```js
+class HBox extends Layout
+```
+
+- **构造函数**：
+  - 设置 CSS 类：`hcontainer`
+- **用途**：横向排布控件。
+
+---
+
+### `bricks.FHBox`
+
+固定行水平盒子（不换行）。
+
+```js
+class FHBox extends HBox
+```
+
+- **构造函数**：
+  - 调用 `super(options)`
+  - 设置样式：`flexWrap: 'nowrap'`
+- **用途**：确保子元素始终在同一行显示。
+
+---
+
+### `bricks.FVBox`
+
+固定列垂直盒子（不换行）。
+
+```js
+class FVBox extends VBox
+```
+
+- **构造函数**：
+  - 设置样式：`flexWrap: 'nowrap'`
+- **用途**：防止垂直方向上的内容换列（较少见，通常用于嵌套场景）。
+
+---
+
+### `bricks.Filler`
+
+弹性填充占位符，常用于 Flex 布局中占据剩余空间。
+
+```js
+class Filler extends Layout
+```
+
+- **构造函数**：
+  - 设置 CSS 类：`filler`
+  - 注释中包含潜在增强样式（如 `flexGrow: 1`），可用于扩展
+- **用途**：在布局中插入空白区域以平衡界面。
+
+---
+
+### `bricks.ResponsableBox`
+
+响应式布局容器，根据宽高比动态调整布局方向。
+
+```js
+class ResponsableBox extends Layout
+```
+
+- **事件绑定**：
+  - 监听 `'element_resize'` 事件，自动调用 `reset_type()`
+- **`reset_type(event)` 行为**：
+  - 判断当前容器宽度与高度：
+    - 若 `width > height` → 视为横向，应用 `hcontainer` 并设 `height: 100%`
+    - 否则 → 视为纵向，应用 `vcontainer` 并设 `width: 100%`
+  - 输出调试日志到控制台
+
+> 💡 此类适合移动端或窗口缩放频繁的场景，实现“自适应”UI 排列。
+
+---
+
+## 键盘选择机制
+
+### 全局栈管理
+
+```js
+bricks.key_selectable_stack = [];
+```
+
+- 所有启用了键盘选择的 `Layout` 实例按进入顺序压入栈。
+- 最顶层的实例才响应按键事件（通过 `is_currkeyselectable()` 判断）。
+
+### 关键方法
+
+| 方法 | 说明 |
+|------|------|
+| `enable_key_select()` | 启用键盘选择，注册事件监听，推入栈 |
+| `disable_key_select()` | 停止监听，从栈顶弹出自身（若为当前层） |
+| `is_currkeyselectable()` | 判断自己是否处于栈顶且可选 |
+
+### 导航逻辑
+
+| 键盘按键 | 功能 |
+|--------|------|
+| `ArrowDown` | 选择下一个子项（循环） |
+| `ArrowUp`   | 选择上一个子项（循环） |
+| `ArrowRight` | 进入下一级（进入当前选中项的子菜单） |
+| `ArrowLeft`  | 返回上一级（退出当前层级） |
+| `Enter`      | 触发当前选中项的 `click` 事件 |
+
+> 🔄 循环选择：到达末尾后回到开头，反之亦然。
+
+---
+
+## 事件处理
+
+### `key_handler(event)`
+
+主键盘事件处理器，仅当实例位于 `key_selectable_stack` 栈顶时生效。
+
+- 使用 `event.key` 匹配方向键与回车
+- 分发对应操作（上下选择、进出层级、确认）
+
+### 生命周期事件
+
+- `on_parent`：当控件被添加或移除父容器时派发，通知父子关系变更
+
+---
+
+## 方法说明
+
+### 控件管理
+
+| 方法 | 参数 | 描述 |
+|------|------|------|
+| `add_widget(w, index)` | `w`: widget, `index?`: number | 将控件插入指定位置或追加至末尾 |
+| `remove_widget(w)` | `w`: widget | 移除指定控件，清理 DOM 和事件 |
+| `clear_widgets()` | 无 | 清空所有子控件及 DOM 子节点 |
+| `remove_widgets_at_begin(cnt)` | `cnt`: number | 移除前 `cnt` 个子控件 |
+| `remove_widgets_at_end(cnt)` | `cnt`: number | 移除后 `cnt` 个子控件 |
+
+> ✅ `insertBefore` / `appendChild` 被合理使用以维持 DOM 结构一致性。
+
+---
+
+### UI 构建方法
+
+| 方法 | 功能 |
+|------|------|
+| `build_title()` / `build_title_widget()` | 创建并添加标题控件（`Title3`） |
+| `build_description()` / `build_description_widget()` | 添加描述文本（`Text`） |
+| `build_toolbar_widget(ext_tools)` | 构建浮动图标工具栏（`FloatTextIconBar`） |
+
+> 🔔 多数构建方法检查是否存在对应属性（如 `this.title`）后再创建。
+
+---
+
+### 选择控制方法
+
+| 方法 | 功能 |
+|------|------|
+| `select_item(w)` | 选中指定控件，取消之前的选择 |
+| `select_default_item()` | 默认选择第一个子控件 |
+| `select_next_item()` | 向下循环选择 |
+| `select_previous_item()` | 向上循环选择 |
+| `find_first_keyselectable_child()` | 深度优先查找首个支持键盘选择的后代 |
+
+---
+
+### 层级跳转
+
+| 方法 | 功能 |
+|------|------|
+| `down_level()` | 进入当前选中控件的子层级（需支持 keyselectable） |
+| `up_level()` | 退出当前层级，返回上级 |
+
+> 🧭 类似菜单树导航模型，利用栈维护路径。
+
+---
+
+## 工厂注册
+
+以下类型已向 `bricks.Factory` 注册，可用于声明式创建：
+
+```js
+bricks.Factory.register('HBox', bricks.HBox);
+bricks.Factory.register('FHBox', bricks.FHBox);
+bricks.Factory.register('VBox', bricks.VBox);
+bricks.Factory.register('FVBox', bricks.FVBox);
+bricks.Factory.register('Filler', bricks.Filler);
+bricks.Factory.register('HFiller', bricks.Filler); // 水平填充
+bricks.Factory.register('VFiller', bricks.Filler); // 垂直填充（同 Fillers）
+bricks.Factory.register('ResponsableBox', bricks.ResponsableBox);
+```
+
+> ✅ 支持模板引擎或 JSON 配置动态生成界面。
+
+---
+
+## 示例用法
+
+### 创建带标题的垂直布局
+
+```js
+let vbox = new bricks.VBox({
+  title: "用户设置",
+  description: "请选择要修改的选项",
+  keyselectable: true
+});
+
+// 添加子控件
+let btn1 = new bricks.Button({ otext: "个人资料" });
+let btn2 = new bricks.Button({ otext: "安全设置" });
+
+vbox.add_widget(btn1);
+vbox.add_widget(btn2);
+
+document.body.appendChild(vbox.dom_element);
+```
+
+### 启用手动键盘导航
+
+```js
+vbox.enable_key_select(); // 激活键盘控制
+```
+
+此时可用 ↑↓ 键切换按钮，Enter 执行点击，← 返回上级（如果有）。
+
+### 响应式容器示例
+
+```js
+let responsive = new bricks.ResponsableBox();
+responsive.add_widget(new bricks.Label({ otext: "此布局会随尺寸变化!" }));
+document.body.appendChild(responsive.dom_element);
+```
+
+窗口大小改变时，布局方向将自动调整。
+
+---
+
+## 注意事项与最佳实践
+
+1. **避免重复启用 `keyselectable`**
+   - 确保 `enable_key_select()` 不被多次调用导致重复绑定事件
+2. **手动管理栈结构风险**
+   - `key_selectable_stack` 是全局状态，跨组件交互需谨慎
+3. **DOM 更新同步**
+   - 所有 `add_widget` / `remove_widget` 都应及时更新 DOM 和 `children` 数组
+4. **性能优化建议**
+   - `find_first_keyselectable_child()` 使用递归，深层嵌套可能影响性能，可缓存结果
+5. **i18n 支持**
+   - 所有文本控件启用 `i18n: true`，便于国际化
+
+---
+
+## 总结
+
+`bricks.Layout` 提供了一个强大而灵活的基础布局系统，结合键盘导航与响应式能力，非常适合构建复杂的桌面风格 Web 应用界面（如仪表盘、菜单系统、表单布局等）。其模块化设计使得扩展新布局类型变得简单，同时工厂模式支持运行时动态渲染。
+
+> ✅ 推荐在需要高可访问性（Accessibility）和键盘操作支持的应用中使用此组件体系。
+
+--- 
+
+📌 **版本信息**：本文档基于提供的 JavaScript 代码片段撰写  
+📅 **最后更新**：2025年4月5日
\ No newline at end of file
diff --git a/aidocs/line.md b/aidocs/line.md
new file mode 100644
index 0000000..ba766ad
--- /dev/null
+++ b/aidocs/line.md
@@ -0,0 +1,203 @@
+# `bricks.ChartLine` 技术文档
+
+> 基于 ECharts 扩展的折线图组件，用于快速渲染多系列折线图。
+
+---
+
+## 概述
+
+`bricks.ChartLine` 是 `bricks.EchartsExt` 的子类，封装了基于 ECharts 的折线图配置逻辑。它支持从远程数据源或本地数据动态生成折线图，并自动构建图表所需的 `options` 配置对象。
+
+该组件通过工厂模式注册为 `'ChartLine'` 类型，可通过 `bricks.Factory.create('ChartLine', config)` 实例化。
+
+---
+
+## 依赖
+
+- `bricks.EchartsExt`：基础 ECharts 扩展类。
+- `bricks.Factory`：用于组件注册与创建的工厂类。
+
+---
+
+## 属性（配置项）
+
+| 属性名         | 类型     | 必填 | 描述 |
+|----------------|----------|------|------|
+| `data_url`     | String   | 否   | 数据请求的 URL 地址。若提供，则通过 AJAX 获取数据。 |
+| `data_params`  | Object   | 否   | 请求数据时携带的参数（GET 或 POST）。 |
+| `method`       | String   | 否   | 请求方法，默认为 `'GET'`。可选 `'POST'`。 |
+| `data`         | Array    | 否   | 直接传入的本地数据数组，格式为对象数组。例如：`[{name: 'A', value1: 10, value2: 20}]`。 |
+| `line_options` | Object   | 否   | 自定义 ECharts 配置的扩展选项，会合并到最终的 `options` 中。 |
+| `nameField`    | String   | 是   | 用作 X 轴分类字段的键名（如时间、类别等）。 |
+| `valueFields`  | Array<String> | 是 | 一个字符串数组，表示需要绘制为折线的字段名称（Y 轴数据）。每个字段将生成一条折线。 |
+
+> ⚠️ 注意：`data` 和 `data_url` 二选一。若两者都存在，优先使用 `data_url` 异步加载数据。
+
+---
+
+## 方法
+
+### `values_from_data(data, name)`
+
+从数据数组中提取指定字段的所有值。
+
+#### 参数
+- `data` (Array<Object>)：数据对象数组。
+- `name` (String)：要提取的字段名。
+
+#### 返回值
+- Array：包含所有 `data[i][name]` 值的数组。
+
+#### 示例
+```js
+const data = [{x: 'A', y: 1}, {x: 'B', y: 2}];
+this.values_from_data(data, 'y'); // 返回 [1, 2]
+```
+
+---
+
+### `lineinfo_from_data(data, name)`
+
+生成单条折线的 ECharts 系列配置项。
+
+#### 参数
+- `data` (Array<Object>)：原始数据。
+- `name` (String)：对应 `valueFields` 中的字段名，作为该折线的名称和数据来源。
+
+#### 返回值
+```js
+{
+  name: String,
+  type: 'line',
+  data: Array // 提取自 data 中对应字段的值
+}
+```
+
+#### 示例
+```js
+this.lineinfo_from_data(data, 'sales');
+// 返回：
+// {
+//   name: 'sales',
+//   type: 'line',
+//   data: [100, 150, 200]
+// }
+```
+
+---
+
+### `setup_options(data)`
+
+根据输入数据构建完整的 ECharts 配置对象。
+
+#### 参数
+- `data` (Array<Object>)：待处理的数据数组。
+
+#### 返回值
+返回标准的 ECharts `options` 对象，结构如下：
+
+```js
+{
+  tooltip: { trigger: 'axis' },
+  legend: { data: valueFields },
+  xAxis: {
+    type: 'category',
+    data: [/* 所有 nameField 对应的值 */]
+  },
+  yAxis: {
+    type: 'value'
+  },
+  series: [/* 多个 lineinfo_from_data 生成的对象 */]
+}
+```
+
+#### 内部流程
+1. 提取 `nameField` 字段作为 X 轴数据。
+2. 遍历 `valueFields`，每项生成一条折线系列。
+3. 构建图例（legend）为 `valueFields` 数组。
+4. 设置提示框为轴触发（`axis`）。
+5. 返回完整配置。
+
+---
+
+## 使用示例
+
+### HTML 结构
+```html
+<div id="chart-line" style="width: 800px; height: 400px;"></div>
+```
+
+### JavaScript 初始化
+
+#### 方式一：使用本地数据
+```js
+const chart = new bricks.ChartLine({
+  data: [
+    { month: 'Jan', sales: 100, profit: 60 },
+    { month: 'Feb', sales: 130, profit: 70 },
+    { month: 'Mar', sales: 145, profit: 65 }
+  ],
+  nameField: 'month',
+  valueFields: ['sales', 'profit']
+});
+
+chart.renderTo('#chart-line');
+```
+
+#### 方式二：从接口加载数据
+```js
+const chart = new bricks.ChartLine({
+  data_url: '/api/chart-data',
+  data_params: { year: 2023 },
+  method: 'GET',
+  nameField: 'date',
+  valueFields: ['pv', 'uv', 'orders']
+});
+
+chart.renderTo('#chart-line');
+```
+
+---
+
+## 图表效果说明
+
+- 支持多条折线同时展示。
+- X 轴为类目轴（category），显示 `nameField` 的值。
+- Y 轴为数值轴（value）。
+- 鼠标悬停时显示坐标轴对齐的提示框（tooltip）。
+- 图例自动根据 `valueFields` 生成。
+
+---
+
+## 注册信息
+
+```js
+bricks.Factory.register('ChartLine', bricks.ChartLine);
+```
+
+可通过工厂方式创建：
+```js
+const chart = bricks.Factory.create('ChartLine', config);
+```
+
+---
+
+## 注意事项
+
+1. 数据必须是对象数组格式。
+2. `nameField` 和 `valueFields` 中的字段必须存在于数据对象中。
+3. 若使用 `data_url`，后端需返回 JSON 格式数组。
+4. 可通过 `line_options` 进行高级定制（如颜色、样式、动画等），会深度合并至最终 options。
+
+---
+
+## 版本信息
+
+- 创建者：`bricks` 框架团队
+- 类型名称：`ChartLine`
+- 继承自：`bricks.EchartsExt`
+- 注册标识符：`'ChartLine'`
+
+--- 
+
+✅ 推荐用于快速搭建基于 ECharts 的多系列折线图场景。
\ No newline at end of file
diff --git a/aidocs/llm.md b/aidocs/llm.md
new file mode 100644
index 0000000..7bd2487
--- /dev/null
+++ b/aidocs/llm.md
@@ -0,0 +1,414 @@
+以下是针对您提供的 JavaScript 代码编写的 **Markdown 格式技术文档**，结构清晰、注释完整，适用于前端开发团队或项目维护者使用。
+
+---
+
+# 📘 `bricks.LlmIO` 模块技术文档
+
+> 基于 `bricks.js` 框架实现的多模型大语言模型（LLM）交互系统  
+> 支持流式响应、文本转语音（TTS）、用户反馈评分等功能
+
+---
+
+## 🔧 模块结构概览
+
+```js
+bricks = window.bricks || {}
+bricks.LlmMsgAudio     // 音频播放与流式消息处理
+bricks.ModelOutput     // 模型输出 UI 组件
+bricks.LlmModel        // 单个 LLM 模型控制器
+bricks.LlmIO           // 主控容器：管理输入、多个模型和输出展示
+```
+
+所有组件均继承自 `bricks.js` 提供的基础 UI 类（如 `VBox`, `HBox`, `JsWidget` 等），并支持动态构建、事件绑定和异步数据流处理。
+
+---
+
+## 1. `bricks.LlmMsgAudio` —— 流式音频消息处理器
+
+### 功能说明
+用于处理来自后端的流式文本响应，并根据标点符号分段发送至音频播放器。自动检测语言以适配中英文标点。
+
+### 继承关系
+```js
+class LlmMsgAudio extends bricks.UpStreaming
+```
+
+### 构造函数：`constructor(opts)`
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `opts` | Object | 传递给父类的配置项 |
+
+#### 初始化字段：
+- `this.olddata`: 上一次接收到的数据（用于增量比较）
+- `this.data`: 当前累积的完整文本
+- `this.cn_p`: 中文标点符号数组 `[“。”,”，”,”！”,”？”,”\n”]`
+- `this.other_p`: 英文标点符号数组 `[“.”,”,”,”!”, “?”, “\n”]`
+- `this.audio`: 实例化的音频播放器（通过 `AudioPlayer({})` 创建）
+
+### 方法列表
+
+#### ✅ `detectLanguage(text)` → `String`
+尝试使用浏览器内置的 `Intl.LocaleDetector` 推测文本语言。
+
+- 返回示例：`'zh'`, `'en'`
+- 若失败则返回 `'未知'`
+
+> ⚠️ 注意：`Intl.LocaleDetector` 并非所有浏览器都支持，需注意兼容性降级处理。
+
+#### ✅ `send(data)` → `void`
+接收增量数据并进行分句处理，将已完成句子通过 `super.send()` 发送。
+
+##### 工作流程：
+1. 计算新增部分：`newdata = data.slice(this.olddata.length)`
+2. 更新历史数据缓存
+3. 调用 `detectLanguage(this.data)` 判断语言
+4. 使用对应标点分割成句子数组（过滤空字符串）
+5. 将除最后一句外的所有完整句子发送出去
+6. 保留最后未完成句在 `this.data` 中等待下一批数据
+
+> 💡 示例：  
+> 输入 `"你好！今天天气"` → 输出 `"你好!"`，缓存 `"今天天气"`
+
+#### ✅ `async go()` → `Promise<Response>`
+调用父类 `go()` 获取最终响应，并设置音频源为该响应内容。
+
+```js
+await super.go(); 
+this.audio.set_source_from_response(resp);
+```
+
+通常用于非流式场景下的 TTS 音频播放。
+
+---
+
+## 2. `bricks.ModelOutput` —— 模型输出 UI 控件
+
+### 功能说明
+显示单个模型的输出结果，包含图标、加载动画、内容区域及满意度评价功能。
+
+### 继承关系
+```js
+class ModelOutput extends bricks.VBox
+```
+
+### 构造函数：`constructor(opts)`
+
+| 属性 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `modelname` | String | 是 | - | 显示的模型名称 |
+| `icon` | URL/String | 否 | `llm.svg` | 自定义图标路径 |
+| `response_mode` | String | 否 | - | 可选 `'stream'`, `'sync'`, `'async'` |
+| `estimate_url` | URL | 否 | - | 用户反馈提交地址 |
+
+#### 内部组件初始化：
+- `img`: 模型图标 SVG
+- `content`: 主体 HBox 容器
+- `run`: 加载动画组件（`BaseRunning`）
+- `filler`: 实际内容显示区（`LlmOut` 组件）
+- `estimate_w`: 满意度打分组件（点赞/踩）
+
+### 核心方法
+
+#### ✅ `build_estimate_widgets()` → `void`
+创建“结果满意吗？”评分控件（仅当 `estimate_url` 存在时）。
+
+包含：
+- 文本提示：“结果满意吗？”
+- 👍 点赞图标（绑定 `estimate_llm(1)`）
+- 👎 点踩图标（绑定 `estimate_llm(-1)`）
+
+初始状态为隐藏（`.hide()`），可在完成后显示。
+
+#### ✅ `async estimate_llm(val, event)` → `Promise<void>`
+用户点击点赞/点踩时触发，向服务端上报评分。
+
+**请求参数：**
+```json
+{
+  "widgettype": "urlwidget",
+  "options": {
+    "url": this.estimate_url,
+    "params": {
+      "logid": this.logid,
+      "value": val  // 1 或 -1
+    }
+  }
+}
+```
+
+> 执行后禁用评分按钮防止重复提交。
+
+#### ✅ `async update_data(data)` → `Promise<void>`
+更新模型输出内容。
+
+- 移除加载动画 `run`
+- 调用 `filler.update(data)` 渲染内容
+- 支持流式逐步更新
+
+#### ✅ `finish()` → `void`
+生命周期钩子，当前无实际逻辑，可扩展。
+
+---
+
+## 3. `bricks.LlmModel` —— 单个 LLM 模型控制器
+
+### 功能说明
+封装一个 LLM 模型的行为逻辑，包括请求发送、格式化、响应处理等。
+
+### 继承关系
+```js
+class LlmModel extends bricks.JsWidget
+```
+
+### 构造函数：`constructor(llmio, opts)`
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `llmio` | LlmIO 实例 | 上层控制容器引用 |
+| `opts` | Object | 模型配置对象 |
+
+#### 配置项 (`opts`) 支持字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `model` | String | 模型标识符（如 `gpt-3.5-turbo`） |
+| `modelname` | String | 显示名 |
+| `url` | URL | 请求接口地址 |
+| `params` | Object | 固定请求参数 |
+| `input_from` | String | 允许的数据来源标签 |
+| `textvoice` | Boolean | 是否启用 TTS 语音播报 |
+| `tts_url` | URL | TTS 接口地址 |
+| `response_mode` | String | `'stream' \| 'sync' \| 'async'` |
+| `icon` | URL | 图标路径 |
+
+### 核心方法
+
+#### ✅ `render_title()` → `HBox`
+生成顶部标题栏（含图标），点击可打开设置面板（预留接口）。
+
+#### ✅ `show_setup_panel(event)` → `void`
+待实现：点击标题弹出模型配置面板。
+
+#### ✅ `inputdata2uploaddata(data)` → `FormData \| Object`
+将输入数据转换为适合上传的格式，并注入模型相关信息。
+
+- 若是 `FormData`，使用 `.append()` 添加字段
+- 否则直接赋值对象属性
+- 注入 `model` 和 `llmid`
+
+> 特殊逻辑：若 `llmio.model_inputed` 为真，则不添加 `model` 字段（避免重复）
+
+#### ✅ `async model_inputed(data)` → `Promise<void>`
+主入口方法：接收用户输入并发起模型请求。
+
+**行为分支：**
+
+| 模式 | 行为 |
+|------|------|
+| `'stream'` / `'async'` | 使用 `HttpResponseStream` 处理流式响应 |
+| `'sync'` | 使用 `HttpJson` 发起同步 POST 请求 |
+
+流程：
+1. 创建 `ModelOutput` 显示组件并加入页面
+2. 准备请求数据
+3. 根据模式发起请求
+4. 流式情况下逐块调用 `chunk_response(mout, line)`
+
+#### ✅ `is_accept_source(source)` → `Boolean`
+判断是否接受来自指定源的数据。
+
+#### ✅ `llm_msg_format()` → `Object`
+返回默认的消息结构模板：
+
+```js
+{ role: 'assistant', content: "${content}" }
+```
+
+可用于格式化聊天记录。
+
+#### ✅ `chunk_response(mout, l)` → `void`
+处理每一个流式响应片段（每行 JSON 字符串）。
+
+- 去除空白字符
+- 尝试解析 JSON
+- 异步模式下只处理 `status === 'SUCCEEDED'` 的消息
+- 调用 `mout.update_data(d)` 更新 UI
+
+#### ✅ `chunk_ended()` → `void`
+流结束回调（目前仅打印日志）
+
+---
+
+## 4. `bricks.LlmIO` —— 主控容器（LLM 输入输出管理器）
+
+### 功能说明
+集成式组件，提供以下能力：
+- 多模型管理
+- 输入表单弹窗
+- 模型选择弹窗
+- 自动渲染模型输出
+- 支持 TTS 和用户反馈
+
+### 继承关系
+```js
+class LlmIO extends bricks.VBox
+```
+
+### 构造函数：`constructor(opts)`
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `user_icon` | URL | 用户头像图标 |
+| `list_models_url` | URL | 获取可用模型列表的接口 |
+| `input_fields` | Array | 表单字段定义（参考 `bricks.Form`） |
+| `models` | Array | 初始已添加的模型列表 |
+| `tts_url` | URL | TTS 接口地址 |
+| `estimate_url` | URL | 用户反馈提交地址 |
+
+#### 初始化行为：
+- 创建标题栏 `title_w`
+- 创建输出区域 `o_w`（滚动容器）
+- 创建底部操作按钮：
+  - `i_w`: 输入按钮（打开输入表单）
+  - `nm_w`: 添加模型按钮（打开模型搜索窗口）
+- 绑定点击事件
+- 若模型少于 2 个且存在 `tts_url`，启用 `textvoice` 模式
+- 遍历 `models` 初始化每个 `LlmModel`
+
+### 核心方法
+
+#### ✅ `async show_input(params)` → `Promise<void>`
+显示用户输入内容在对话区域上方。
+
+- 构建 `UserInputView` 显示输入数据
+- 添加用户头像图标
+- 插入到 `o_w` 容器中
+
+#### ✅ `show_added_model(m)` → `void`
+注册一个新的模型实例并将其标题添加到顶部工具栏。
+
+- 若启用了 `textvoice`，自动注入 `tts_url`
+- 实例化 `LlmModel`
+- 调用 `.render_title()` 并加入 `title_w`
+
+#### ✅ `async open_search_models(event)` → `Promise<void>`
+打开“选择模型”弹窗，从远程获取模型列表。
+
+使用 `PopupWindow + Cols` 组件展示表格形式的模型列表。
+
+**表格列定义：**
+- 图标 + 名称（HBox）
+- 描述、启用时间（VBox 内嵌 Text）
+
+点击某条记录会触发：
+- `add_new_model(event)`
+- 并关闭弹窗
+
+#### ✅ `async add_new_model(event)` → `Promise<void>`
+将选中的模型加入 `this.models` 数组，并调用 `show_added_model` 显示。
+
+#### ✅ `async open_input_widget(event)` → `Promise<void>`
+打开输入表单弹窗。
+
+使用 `Form` 组件加载 `input_fields` 定义的字段。
+
+提交后触发：
+- `handle_input(event)`
+- 并自动关闭弹窗
+
+#### ✅ `async handle_input(event)` → `Promise<void>`
+处理用户提交的输入数据。
+
+1. 调用 `show_input(params)` 显示输入内容
+2. 遍历所有 `llmmodels`，调度执行各自的 `model_inputed(params)`
+   - 使用 `schedule_once(fn, 0.01)` 实现微任务延迟执行
+
+---
+
+## 📦 注册组件
+
+```js
+bricks.Factory.register('LlmIO', bricks.LlmIO);
+```
+
+允许通过工厂方式动态创建此组件。
+
+---
+
+## 🎯 使用示例
+
+```js
+var llmio = new bricks.LlmIO({
+  user_icon: '/static/icons/user.png',
+  tts_url: '/api/tts',
+  estimate_url: '/api/feedback',
+  input_fields: [
+    { name: 'prompt', label: '输入提示', type: 'textarea' }
+  ],
+  models: [
+    {
+      model: 'qwen-plus',
+      modelname: '通义千问',
+      url: '/api/llm/stream',
+      response_mode: 'stream',
+      icon: '/icons/qwen.svg'
+    }
+  ]
+});
+```
+
+---
+
+## 🛠️ 注意事项 & 待优化点
+
+| 问题 | 建议修复 |
+|------|----------|
+| `detectLaguage` 拼写错误 | 应为 `detectLanguage` |
+| `this.oter_p` 拼写错误 | 应为 `this.other_p` |
+| `lang='zh'` 错误地使用了赋值而非比较 | 应改为 `lang === 'zh'` |
+| `objcopy` 函数未定义 | 应替换为 `JSON.parse(JSON.stringify(data))` 或引入深拷贝工具 |
+| `Intl.LocaleDetector` 兼容性差 | 建议降级为基于关键词的语言识别算法 |
+| `schedule_once(..., 0.01)` 不标准 | 建议改用 `setTimeout(fn, 0)` 或 `queueMicrotask` |
+
+---
+
+## 📚 附录：关键类图（UML 简化版）
+
+```
++------------------+
+|     LlmIO        |
++------------------+
+       |
+       v
++------------------+
+|   LlmModel[x]    |
++------------------+
+       |
+       v
++------------------+
+|  ModelOutput     |
++------------------+---> LlmMsgAudio (用于音频)
+       |
+       v
++------------------+
+|    UserInput     |
++------------------+
+```
+
+---
+
+## 📝 总结
+
+本模块实现了完整的 LLM 交互链路：
+1. 用户输入 → 表单收集
+2. 多模型并发调用 → 支持流式/同步
+3. 分句播放音频 → 提升听觉体验
+4. 用户反馈机制 → 支持效果评估闭环
+
+适合集成于智能客服、AI 助手、教育平台等需要多模型对比或语音播报的应用场景。
+
+--- 
+
+✅ **文档版本：v1.0**  
+📅 最后更新：2025年4月5日  
+👨‍💻 编写：Bricks Framework Team
\ No newline at end of file
diff --git a/aidocs/llm_dialog.md b/aidocs/llm_dialog.md
new file mode 100644
index 0000000..9c961cf
--- /dev/null
+++ b/aidocs/llm_dialog.md
@@ -0,0 +1,366 @@
+# `bricks.js` 技术文档：LlmDialog 模块
+
+> **版本**：1.0  
+> **模块名称**：`LlmDialog`, `LlmMsgBox`, `UserMsgBox`, 工具函数 `escapeSpecialChars`  
+> **依赖框架**：`bricks.js` 前端组件库（基于类的 UI 架构）
+
+---
+
+## 📚 概述
+
+该模块提供了一套用于构建与 LLM（大语言模型）交互对话界面的组件系统，支持多模型并行响应、流式/同步响应模式、Markdown 渲染以及消息内容转义。主要包含以下核心类：
+
+- `bricks.escapeSpecialChars`：字符串特殊字符转义工具。
+- `bricks.UserMsgBox`：用户消息展示组件。
+- `bricks.LlmMsgBox`：LLM 回应消息展示及请求处理组件。
+- `bricks.LlmDialog`：主对话容器，管理整个对话流程。
+
+此外，通过 `bricks.Factory.register` 注册了 `LlmDialog` 以便动态创建。
+
+---
+
+## 🔧 工具函数
+
+### `bricks.escapeSpecialChars(s)`
+
+对输入字符串中的特殊字符进行反斜杠转义，常用于防止 JSON 注入或确保文本安全输出。
+
+#### 参数
+| 参数 | 类型   | 描述         |
+|------|--------|--------------|
+| `s`  | string | 待转义字符串 |
+
+#### 返回值
+- **类型**：`string`
+- 转义后的字符串，适用于嵌入 JSON 或 HTML 环境。
+
+#### 支持转义的字符
+| 字符 | 原始表示 | 转义后表示     | 说明               |
+|------|----------|----------------|--------------------|
+| `\`  | `\`      | `\\`           | 反斜杠             |
+| `"`  | `"`      | `\"`           | 双引号             |
+| `\n` | 换行     | `\n`           | 换行符             |
+| `\r` | 回车     | `\r`           | 回车符             |
+| `\t` | 制表符   | `\t`           | Tab                |
+| `\f` | 换页     | `\f`           | Form feed          |
+| `\v` | 垂直制表 | `\v`           | Vertical tab       |
+| `\0` | 空字符   | `\0`           | Null byte          |
+
+> ⚠️ 注意：单引号 `'` 的转义代码被注释，当前未启用。
+
+#### 示例
+```js
+bricks.escapeSpecialChars('Hello "world"\n'); 
+// 输出: 'Hello \\"world\\"\\n'
+```
+
+---
+
+## 💬 用户消息组件：`UserMsgBox`
+
+继承自 `bricks.HBox`，用于显示用户发送的消息。
+
+### 继承关系
+```js
+class UserMsgBox extends bricks.HBox
+```
+
+### 构造函数：`constructor(opts)`
+
+#### 参数 `opts`
+| 属性       | 类型   | 必需 | 默认值                     | 描述                         |
+|------------|--------|------|----------------------------|------------------------------|
+| `icon`     | string | 否   | `imgs/chat-user.svg`       | 用户头像 SVG 图标 URL        |
+| `prompt`   | string | 是   | -                          | 用户输入的消息内容           |
+| `msg_css`  | string | 否   | `'user_msg'`               | 应用到消息体的 CSS 类名      |
+
+#### 内部结构
+1. 创建一个 SVG 头像图标（使用 `bricks.Svg`）。
+2. 使用 `MdWidget` 显示 Markdown 格式消息。
+3. 添加左侧空白图标占位符（`BlankIcon`），保持布局对齐。
+4. 消息排列顺序：`[BlankIcon] ← [消息内容] ← [用户头像]`
+
+#### 示例实例化
+```js
+new bricks.UserMsgBox({
+  prompt: "你好，请介绍一下你自己。",
+  icon: "/icons/user.svg",
+  msg_css: "custom-user-style"
+});
+```
+
+---
+
+## 🤖 LLM 消息组件：`LlmMsgBox`
+
+继承自 `bricks.HBox`，用于展示 LLM 的回复，并支持流式和同步两种响应方式。
+
+### 继承关系
+```js
+class LlmMsgBox extends bricks.HBox
+```
+
+### 构造函数：`constructor(opts)`
+
+#### 参数 `opts`
+| 属性            | 类型     | 必需 | 默认值                  | 描述                                                                 |
+|------------------|----------|------|-------------------------|----------------------------------------------------------------------|
+| `model`          | string   | 是   | -                       | 使用的模型名称（如 `gpt-3.5-turbo`）                                 |
+| `mapi`           | string   | 是   | -                       | API 类型标识（可用于后端路由判断）                                   |
+| `url`            | string   | 是   | -                       | 请求后端接口地址                                                     |
+| `icon`           | string   | 否   | `imgs/user.png`         | LLM 头像图标 URL                                                    |
+| `msg_css`        | string   | 否   | `'llm_msg'`             | 消息区域应用的 CSS 类                                                |
+| `response_mode`  | string   | 否   | `'stream'`              | 响应模式：`'stream'`, `'sync'`, `'async'`                            |
+| `user_msg`       | object   | 否   | `{role:'user', content:"${prompt}"}` | 用户消息模板，支持 `${prompt}` 插值                                |
+| `llm_msg`        | object   | 否   | `{role:'assistant', content:"${content}"}` | LLM 消息模板，支持 `${content}` 插值                             |
+
+#### 内部初始化逻辑
+- 创建头像图标（SVG）
+- 初始化 `MdWidget` 显示消息内容
+- 加载 `BaseRunning` 动画组件（在响应中显示加载状态）
+- 初始化消息历史数组 `this.messages = []`
+
+#### 消息排列顺序
+`[LLM头像] → [运行动画] → [消息内容] → [空白占位符]`
+
+---
+
+### 方法列表
+
+#### `responsed()`
+标记响应已开始，停止加载动画，移除运行指示器。
+
+```js
+this.run.stop_timepass();
+this.remove_widget(this.run);
+```
+
+#### `user_msg_format()`
+生成用户消息对象格式。
+
+- 若设置了 `this.user_msg`，则返回其值；
+- 否则返回默认模板：`{role: 'user', content: "${prompt}"}`
+
+> 实际内容将在调用时通过 `bricks.apply_data()` 替换 `${prompt}`。
+
+#### `llm_msg_format()`
+生成 LLM 消息对象格式。
+
+- 若设置了 `this.llm_msg`，返回其值；
+- 否则返回：`{role: 'assistant', content: "${content}"}`
+
+#### `chunk_response(l)`
+处理流式响应中的每一个数据块（chunk）。
+
+##### 参数
+- `l`: JSON 字符串片段（通常来自 ReadableStream）
+
+##### 行为
+1. 解析 JSON 数据。
+2. 若无 `content` 字段或为空，忽略。
+3. 累加内容至当前消息。
+4. 更新 `MdWidget` 内容。
+5. 触发 `updated` 事件。
+
+#### `chunk_ended()`
+流式响应结束后，将最终内容保存为结构化消息并推入 `messages` 数组。
+
+- 调用 `escapeSpecialChars` 对内容转义
+- 使用 `apply_data` 填充模板
+- 推入 `this.messages`
+
+#### `async set_prompt(prompt)`
+发起对 LLM 的请求。
+
+##### 参数
+- `prompt`: 用户输入文本（自动转义）
+
+##### 流程
+1. 将用户消息按模板格式化并加入 `messages`。
+2. 准备请求参数：
+   ```js
+   {
+     messages: this.messages,
+     mapi: this.mapi,
+     model: this.model
+   }
+   ```
+3. 根据 `response_mode` 执行不同请求策略：
+
+| 模式      | 行为说明 |
+|-----------|---------|
+| `stream`  | 使用 `HttpResponseStream` 发起 POST 请求，逐块接收并渲染 |
+| `sync`    | 使用 `HttpJson` 同步获取完整响应，一次性渲染结果 |
+| 其他      | 不做任何操作（预留扩展） |
+
+##### 示例调用
+```js
+await llmMsgBox.set_prompt("请写一首关于春天的诗");
+```
+
+---
+
+## 🧩 主对话框组件：`LlmDialog`
+
+继承自 `bricks.VBox`，是完整的聊天对话界面容器，支持多模型同时响应。
+
+### 继承关系
+```js
+class LlmDialog extends bricks.VBox
+```
+
+### 构造函数：`constructor(opts)`
+
+#### 参数 `opts`
+| 属性             | 类型     | 必需 | 默认值         | 描述                                                                 |
+|------------------|----------|------|----------------|----------------------------------------------------------------------|
+| `models`         | array    | 是   | -              | 模型配置数组，每个元素定义一个 LLM 模型                              |
+| `response_mode`  | string   | 否   | `'stream'`     | 全局响应模式：`'stream'`, `'sync'`, `'async'`                        |
+| `user_msg_css`   | string   | 否   | `'user_msg'`   | 用户消息使用的 CSS 类                                               |
+| `user_icon`      | string   | 否   | -              | 用户头像图标路径                                                    |
+| `title_ccs`      | string   | 否   | `'llm_title'`  | 标题栏 CSS 类（拼写疑似错误，应为 `title_css`）                     |
+| `height`         | string   | 否   | `'100%'`       | 容器高度                                                            |
+
+#### `models` 数组项结构
+```js
+{
+  model: "gpt-3.5-turbo",
+  mapi: "openai",
+  url: "/api/openai/chat",
+  icon: "/icons/gpt.svg",
+  css: "gpt-response",
+  user_msg: { role: "user", content: "${prompt}" },
+  llm_msg: { role: "assistant", content: "${content}" }
+}
+```
+
+---
+
+### 方法列表
+
+#### `show_models_info()`
+遍历所有模型，调用 `show_model_info(model)` 在标题栏显示模型信息。
+
+#### `show_model_info(model)`
+在顶部标题区添加一个 HBox，包含模型图标和名称。
+
+- 使用 `Svg` 显示图标
+- 使用 `Text` 显示模型名
+- 存储引用到 `this.model_info_ws[model.model]`
+
+#### `add_model(model)`
+动态添加新模型配置，并立即显示在标题栏。
+
+#### `delete_model(model)`
+根据 `model.model` 名称删除模型及其视图。
+
+#### `async set_prompt(prompt)`
+主入口方法：发送用户消息并触发所有模型响应。
+
+##### 步骤
+1. 转义用户输入。
+2. 创建并添加 `UserMsgBox` 到滚动面板。
+3. 调用 `llm_request(prompt)` 并等待完成。
+4. 自动滚动到底部。
+
+#### `async llm_request(prompt)`
+为每个注册的模型创建一个 `LlmMsgBox`，并异步启动请求。
+
+- 使用 `schedule_once(fn, 0.1)` 延迟执行以避免阻塞 UI
+- 所有模型并行响应
+
+---
+
+### 事件机制
+
+#### `llm_answer` 事件
+当某个模型完成响应后，可通过监听此事件获取回答内容。
+
+> ❗ 当前代码中未显式触发 `llm_answer` 事件，需补充如下代码才能生效：
+```js
+// 在 chunk_ended 或 sync 响应结束处添加：
+this.fire('llm_answer', { content: txt });
+```
+
+建议增强事件通知能力。
+
+---
+
+## 🏗️ 工厂注册
+
+```js
+bricks.Factory.register('LlmDialog', bricks.LlmDialog);
+```
+
+允许通过字符串标识动态创建组件：
+```js
+var dialog = bricks.Factory.create('LlmDialog', options);
+```
+
+---
+
+## ✅ 使用示例
+
+```js
+var dialog = new bricks.LlmDialog({
+  height: '600px',
+  user_icon: '/icons/me.svg',
+  title_ccs: 'chat-title',
+  response_mode: 'stream',
+  models: [
+    {
+      model: 'gpt-3.5-turbo',
+      mapi: 'openai',
+      url: '/api/chat',
+      icon: '/icons/gpt.svg',
+      css: 'gpt-msg',
+      user_msg: { role: 'user', content: '${prompt}' },
+      llm_msg: { role: 'assistant', content: '${content}' }
+    },
+    {
+      model: 'claude-2',
+      mapi: 'anthropic',
+      url: '/api/anthropic',
+      icon: '/icons/claude.svg',
+      css: 'claude-msg'
+    }
+  ]
+});
+
+document.body.appendChild(dialog.dom_element);
+
+// 发送消息
+dialog.set_prompt("解释什么是机器学习");
+```
+
+---
+
+## 📝 注意事项与改进建议
+
+| 项目 | 说明 |
+|------|------|
+| 🔐 安全性 | `escapeSpecialChars` 有助于防止注入，但建议结合 DOMPurify 或其他 sanitizer 进一步防护 XSS |
+| 🧩 单引号转义 | 被注释掉，若需兼容 SQL 或属性字符串场景，建议启用 |
+| 🎯 事件缺失 | `llm_answer` 事件未实际触发，建议在 `chunk_ended()` 中补全 |
+| 🖼️ 图标资源 | 依赖 `bricks_resource()` 函数解析静态资源路径，需确保其存在 |
+| ⏳ 异步控制 | `schedule_once(..., 0.1)` 是一种 Hack，可考虑改为 `queueMicrotask` 或 `Promise.resolve().then()` |
+| 📏 布局兼容 | 使用 Flexbox（HBox/VBox），确保父级容器设置正确尺寸 |
+
+---
+
+## 📚 总结
+
+本模块提供了完整的前端 LLM 聊天对话解决方案，具备以下特性：
+
+✅ 多模型支持  
+✅ 流式 & 同步响应  
+✅ Markdown 渲染  
+✅ 自动滚动与加载动画  
+✅ 可扩展模板机制  
+
+适合集成进低代码平台、AI 助手界面、多模型对比测试工具等场景。
+
+--- 
+
+> 文档版本：1.0  
+> 最后更新：2025年4月5日
\ No newline at end of file
diff --git a/aidocs/llmout.md b/aidocs/llmout.md
new file mode 100644
index 0000000..6b93413
--- /dev/null
+++ b/aidocs/llmout.md
@@ -0,0 +1,297 @@
+# Bricks 框架技术文档
+
+## 概述
+
+本文档描述了 `bricks` 框架中两个核心视图类的实现与使用：`UserInputView` 和 `LlmOut`。这两个类用于处理用户输入和大模型输出内容的可视化展示，支持 Markdown 文本、图像、音频、视频等多种媒体类型。
+
+---
+
+## 1. `bricks.UserInputView`
+
+### 类定义
+```javascript
+bricks.UserInputView = class extends bricks.VBox
+```
+
+### 功能说明
+将用户的输入字段（如文本、图片、音视频等）转换为结构化的 Markdown 内容进行展示，并独立嵌入音视频播放器组件。
+
+- 所有非音视频字段以代码块形式显示。
+- 图像字段以 Markdown 图像语法渲染。
+- 视频和音频字段通过专用播放器组件独立展示。
+
+---
+
+### 构造函数
+```javascript
+constructor(opts)
+```
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `opts` | Object | 配置选项，继承自 `bricks.VBox` |
+
+#### 初始化行为
+- 调用父类构造函数 `super(opts)`
+- 初始化内部变量：
+  - `this.v_w`: 视频播放器实例（初始为 `null`）
+  - `this.a_w`: 音频播放器实例（初始为 `null`）
+- 调用 `show_input(this.data)` 显示数据
+
+---
+
+### 方法：`show_input(data)`
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `data` | Object | 包含用户输入数据的对象 |
+
+#### 处理逻辑
+遍历 `this.input_fields` 中定义的字段配置，根据字段名前缀判断类型并生成相应内容：
+
+| 字段前缀 | 处理方式 |
+|---------|----------|
+| `video*` | 创建 `VideoPlayer` 组件，自动播放，宽度 100% |
+| `audio*` | 创建 `AudioPlayer` 组件，自动播放，宽度 100% |
+| `image*` | 在 Markdown 中添加图片语法：`![label](url)` |
+| 其他     | 使用代码块包裹内容：`\`\`\`\nvalue\n\`\`\`` |
+
+> **注意**：字段标签优先使用 `f.label`，若无则使用 `f.name`
+
+#### 流程步骤
+1. 初始化空字符串 `mdtext`
+2. 遍历所有输入字段，拼接 Markdown 内容或创建媒体组件
+3. 清除当前所有子组件（`clear_widgets()`）
+4. 创建新的 `MdWidget` 显示 Markdown 内容
+5. 添加音视频组件（如有）
+
+#### 示例输出 Markdown
+```markdown
+* 用户提问
+```
+这是用户的输入文本
+```
+
+* 示例图片
+![示例图片](https://example.com/image.png)
+```
+
+---
+
+### 属性
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `v_w` | VideoPlayer 或 null | 当前绑定的视频播放器 |
+| `a_w` | AudioPlayer 或 null | 当前绑定的音频播放器 |
+| `input_fields` | Array | 字段定义数组，需在外部设置 |
+| `data` | Object | 输入数据对象 |
+
+---
+
+## 2. `bricks.LlmOut`
+
+### 类定义
+```javascript
+bricks.LlmOut = class extends bricks.VBox
+```
+
+### 功能说明
+用于动态渲染大语言模型（LLM）返回的结果数据。支持以下内容类型：
+
+- 推理过程文本（thinking / reasoning）
+- 最终回答内容
+- 错误信息
+- 音频响应（URL 或 Base64）
+- 视频响应（URL 或 Base64）
+- 单张或多张图像
+
+该组件具备增量更新能力，可通过多次调用 `update()` 累积内容。
+
+---
+
+### 构造函数
+```javascript
+constructor(opts)
+```
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `opts` | Object | 配置选项，继承自 `VBox` |
+
+#### 初始化行为
+- 调用父类构造函数
+- 初始化各类媒体组件引用为 `null`
+- 初始化数据缓存属性为空值或空数组
+
+#### 初始状态
+```js
+this.rc_w = null;           // reasoning widget
+this.c_w = null;            // content widget
+this.v_w = null;            // video player
+this.i_w = null;            // image widgets (not used directly)
+this.a_w = null;            // audio player
+this.images = [];           // 存储图片 URL 列表
+this.reasoning_content = ''; // 缓存推理内容
+this.content = '';          // 缓存应答内容
+this.error = '';            // 缓存错误信息
+```
+
+---
+
+### 方法：`update(data)`
+
+#### 参数
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `data` | Object | 是 | LLM 返回的 JSON 数据 |
+
+#### 支持字段
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| `reasoning_content` | String | 推理过程文本（可选） |
+| `content` | String | 最终回复文本（可选） |
+| `error` | String | 错误信息（可选） |
+| `audio` | String | 音频资源路径或 Base64 编码（可选） |
+| `video` | String | 视频资源路径或 Base64 编码（可选） |
+| `image` | String 或 Array<String> | 图片资源地址（单个或多个） |
+
+---
+
+#### 处理逻辑详解
+
+##### 🔊 音频处理
+- 若 `audio` 不以 `http` 开头且不包含 `data:audio/` 前缀，则自动封装为 `data:audio/wav;base64,...`
+- 第一次出现时创建 `AudioPlayer`
+- 后续调用会追加新音频（`add_url`）
+
+##### 🎥 视频处理
+- 第一次出现创建 `VideoPlayer`
+- 后续更新追加新视频源（`add_url`）
+
+##### ❌ 错误处理
+- 将 `data.error` 追加到本地缓存 `this.error`
+- 展示时使用 `resp-error` CSS 类样式化
+
+##### 💬 推理内容
+- 追加至 `this.reasoning_content`
+- 使用 `thinking-content` 样式及浅红色背景 (`#f0d0d0`) 区分显示
+
+##### ✅ 正常响应内容
+- 追加至 `this.content`
+- 使用 `resp-content` 样式正常展示
+
+##### 🖼️ 图像处理
+- 支持单个 URL 或数组
+- 所有图像 URL 被合并进 `this.images` 数组
+- 每张图创建一个 `Image` 组件并添加到容器
+
+---
+
+#### 渲染顺序
+组件按如下顺序依次添加到界面：
+
+1. 错误信息（若有）
+2. 推理内容（若有）
+3. 正常响应内容（若有）
+4. 视频播放器（若有）
+5. 音频播放器（若有）
+6. 所有图片（逐一添加）
+
+> **注意**：每次 `update()` 都会先清除已有组件（`clear_widgets()`），再重新构建整个 UI。
+
+---
+
+### 注册信息
+```js
+bricks.Factory.register('LlmOut', bricks.LlmOut);
+```
+允许通过工厂模式以字符串 `'LlmOut'` 实例化此类。
+
+---
+
+## 使用示例
+
+### 示例 1：初始化 UserInputView
+```js
+const userInput = new bricks.UserInputView({
+  data: {
+    question: "你好吗？",
+    image_01: "https://example.com/photo.jpg"
+  },
+  input_fields: [
+    { name: "question", label: "问题" },
+    { name: "image_01", label: "上传图片" }
+  ]
+});
+```
+
+### 示例 2：更新 LLM 输出
+```js
+const llmView = new bricks.LlmOut();
+
+llmView.update({
+  reasoning_content: "正在分析用户的问题...",
+  audio: "base64encodedstring==",
+  image: ["img1.jpg", "img2.jpg"]
+});
+
+llmView.update({
+  content: "我已经完成分析，这是结果。",
+  video: "https://example.com/demo.mp4"
+});
+```
+
+---
+
+## 依赖说明
+
+| 组件 | 用途 |
+|------|------|
+| `bricks.VBox` | 布局容器基类，垂直排列子组件 |
+| `bricks.MdWidget` | 渲染 Markdown 内容 |
+| `bricks.VideoPlayer` | 视频播放组件 |
+| `bricks.AudioPlayer` | 音频播放组件 |
+| `bricks.Image` | 图像显示组件 |
+| `bricks.escapeSpecialChars()` | 工具函数，转义特殊字符防止 XSS |
+
+---
+
+## 注意事项
+
+1. **Base64 音频格式假设**：默认非 HTTP 音频数据为 WAV 格式的 Base64 编码。
+2. **图像数组合并问题**：当前 `concat()` 未正确赋值，应改为：
+   ```js
+   this.images = this.images.concat(data.image);
+   ```
+3. **增量更新限制**：虽然内容是累积的，但每次都会重绘全部组件，可能影响性能。
+4. **样式依赖**：需要预定义 CSS 类：
+   - `resp-error`
+   - `thinking-content`
+   - `resp-content`
+
+---
+
+## 待优化建议
+
+| 项目 | 建议 |
+|------|------|
+| 图像去重 | 可增加 URL 去重机制 |
+| 媒体并发 | 多个音视频同时播放可能干扰用户体验 |
+| 安全性 | `escapeSpecialChars` 应确保防御 XSS 注入 |
+| 性能 | 大量文本更新时避免频繁 DOM 重绘 |
+
+---
+
+## 版本信息
+
+- 框架：Bricks UI Framework
+- 模块：`UserInputView`, `LlmOut`
+- 作者：系统自动生成文档
+- 时间：2025年4月5日
+
+--- 
+
+✅ 文档结束
\ No newline at end of file
diff --git a/aidocs/markdown_viewer.md b/aidocs/markdown_viewer.md
new file mode 100644
index 0000000..bac39c7
--- /dev/null
+++ b/aidocs/markdown_viewer.md
@@ -0,0 +1,250 @@
+# Bricks Markdown 组件技术文档
+
+> **项目依赖说明**：本组件基于 [marked.js](https://github.com/markedjs/marked) 实现 Markdown 渲染功能。在使用 `bricks.js` 前，需确保已引入 `marked.min.js`。
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+```
+
+---
+
+## 模块概述
+
+`bricks.MdWidget` 与 `bricks.MarkdownViewer` 是 Bricks 框架中用于渲染和交互式浏览 Markdown 内容的两个核心组件：
+
+- `MdWidget`：基础 Markdown 显示控件，支持本地文本或远程 URL 加载。
+- `MarkdownViewer`：增强型 Markdown 浏览器，内置导航栈（前进/后退）功能，适合构建文档阅读器类应用。
+
+---
+
+## 1. `bricks.MdWidget`
+
+### 类定义
+```js
+class MdWidget extends bricks.JsWidget
+```
+
+### 功能描述
+一个轻量级的 Markdown 渲染控件，可从字符串 (`mdtext`) 或远程 URL (`md_url`) 加载内容，并使用 `marked.js` 进行解析渲染。支持动态更新内容和链接拦截处理。
+
+### 构造函数参数：`options`
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `mdtext` | String | 否 | 要渲染的 Markdown 文本内容 |
+| `md_url` | String | 否 | 远程 Markdown 文件 URL |
+| `method` | String | 否（默认 `"GET"`） | 请求方式（目前仅支持 GET） |
+| `params` | Object | 否 | 请求参数（暂未实际用于 GET 请求） |
+
+> ⚠️ 注意：若同时提供 `mdtext` 和 `md_url`，优先使用 `mdtext` 并立即渲染。
+
+### 方法列表
+
+#### `constructor(options)`
+初始化组件：
+- 若提供了 `mdtext`，则直接调用 `_build1()` 渲染。
+- 否则延迟加载 `md_url` 内容，并绑定滚动监听。
+
+#### `set_content(content)`
+动态设置 Markdown 内容并重新渲染。
+
+- **参数**：
+  - `content`: (String) 新的 Markdown 字符串
+
+#### `show_scroll(event)`
+滚动事件回调，输出当前 `window.scrollY` 到调试日志（通过 `bricks.debug`）。
+
+#### `async build()`
+异步加载并渲染来自 `opts.md_url` 的 Markdown 内容。若未指定 URL，则不执行任何操作。
+
+#### `async _build(md_url)`
+私有方法：通过 `bricks.tget(md_url)` 获取远程 Markdown 内容并渲染。
+
+- 触发事件：`loaded`，携带 `{ url: md_url }`
+- 自动重写页面内所有 `<a>` 标签为内部跳转行为
+
+#### `_build1()`
+将当前 `this.md_content` 使用 `marked.parse()` 解析为 HTML，并插入 DOM。
+同时劫持所有链接点击事件，实现内部导航。
+
+> 所有 `<a href="...">` 被改为 `href="#"`，并绑定 `onclick` 调用 `_build(原URL)`。
+
+#### `getname()`
+返回控件名称：
+- 若设置了 `this.name`，返回该值；
+- 否则返回 `'mdtext'`
+
+#### `getValue()`
+获取当前控件的值，格式为对象：
+```js
+{ [name]: md_content }
+```
+常用于表单数据收集。
+
+#### `setValue(v)`
+设置 Markdown 内容（仅赋值，不触发渲染）。通常配合其他逻辑调用。
+
+---
+
+## 2. `bricks.MarkdownViewer`
+
+### 类定义
+```js
+class MarkdownViewer extends bricks.VBox
+```
+
+### 功能描述
+一个容器式 Markdown 浏览器，继承自 `VBox`，支持以下特性：
+- 可选的“返回”按钮（导航栈）
+- 支持点击 Markdown 中的链接进行页面跳转
+- 记录访问历史（back_stack），支持回退至上一页
+
+### 构造函数参数：`options`
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `navigator` | Boolean | 否（默认 `true`） | 是否显示返回按钮 |
+| `recommentable` | Boolean | 否 | （预留字段，当前未使用） |
+| `md_url` | String | 否 | 初始加载的远程 Markdown URL |
+| `mdtext` | String | 否 | 初始本地 Markdown 文本 |
+| `method` | String | 否（默认 `"GET"`） | HTTP 方法 |
+| `params` | Object | 否 | 请求参数对象 |
+
+> ✅ 提示：使用 `absurl()` 处理相对路径，确保 URL 正确解析。
+
+### 方法列表
+
+#### `constructor(options)`
+初始化组件：
+- 创建内部 `MdWidget` 实例负责渲染
+- 注册 `loaded` 事件以维护导航栈
+- 设置样式：自动滚动、占满父容器高度
+
+#### `show_scroll(event)`
+同 `MdWidget`，打印当前滚动位置。
+
+#### `async createBackButton()`
+动态创建顶部返回按钮（HBox + Text 组合）：
+- 显示文本 `"<<<<<<<"`
+- 点击触发 `go_back()`
+- 使用 `widgetBuild` 异步生成 UI 元素（调试信息较多）
+
+> 🛠️ 当前 UI 较原始，未来可替换为图标或更美观样式。
+
+#### `add_back_stack(event)`
+当新页面加载完成时，将当前 URL 推入 `back_stack` 数组。
+
+- **事件参数**：`event.params.url` 表示刚加载的 URL
+
+#### `async go_back(event)`
+实现“返回上一页”逻辑：
+1. 弹出当前页 URL
+2. 再弹出上一页 URL
+3. 使用 `mdtext._build(url)` 加载上一页内容
+
+> 🔒 若栈长度小于 2，则禁止返回。
+
+#### `async build()` / `async _build(md_url)`
+> ❗注意：此处存在代码冗余 —— `_build` 方法在 `MarkdownViewer` 中重复定义但未被调用（应调用的是 `mdtext._build`）。
+
+建议移除该方法或修正逻辑，避免混淆。
+
+---
+
+## 事件系统
+
+### 自定义事件
+
+| 事件名 | 触发时机 | 携带参数 |
+|--------|----------|---------|
+| `loaded` | Markdown 内容成功加载并渲染后 | `{ url: string }` |
+| `scroll` | 容器发生滚动时（绑定到 DOM） | 原生 Event 对象 |
+
+可通过 `.bind('event', handler)` 监听。
+
+---
+
+## 工厂注册
+
+```js
+bricks.Factory.register('MarkdownViewer', bricks.MarkdownViewer);
+bricks.Factory.register('MdWidget', bricks.MdWidget);
+```
+
+允许通过 JSON 描述符动态创建组件：
+
+### 示例 JSON 配置
+
+```json
+{
+  "widgettype": "MarkdownViewer",
+  "options": {
+    "md_url": "/docs/intro.md",
+    "navigator": true
+  }
+}
+```
+
+---
+
+## 使用示例
+
+### 示例 1：直接渲染本地 Markdown
+
+```js
+const mdWidget = new bricks.MdWidget({
+  mdtext: "# Hello\nWelcome to Bricks Markdown Viewer!"
+});
+document.body.appendChild(mdWidget.dom_element);
+```
+
+### 示例 2：加载远程 Markdown 并启用导航
+
+```js
+const viewer = new bricks.MarkdownViewer({
+  md_url: 'https://example.com/README.md',
+  navigator: true
+});
+document.body.appendChild(viewer.dom_element);
+```
+
+### 示例 3：动态更新内容
+
+```js
+mdWidget.set_content("## New Content\nUpdated at " + new Date().toLocaleString());
+```
+
+---
+
+## 注意事项 & 建议
+
+1. **依赖必须提前加载**
+   ```html
+   <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+   ```
+
+2. **安全性提示**
+   - `innerHTML = marked.parse(...)` 存在 XSS 风险
+   - 如需展示用户输入，请先对 HTML 输出做净化处理（如使用 DOMPurify）
+
+3. **性能优化建议**
+   - 避免频繁调用 `set_content` 或 `_build`
+   - 对大型文档考虑分页或懒加载
+
+4. **代码改进建议**
+   - `MarkdownViewer._build` 方法冗余且可能错误，建议删除或重构
+   - `createBackButton` 应支持国际化或自定义文本
+   - 链接拦截逻辑可抽象成独立方法便于复用
+
+---
+
+## 版本信息
+
+- **作者**：Bricks Framework 团队
+- **依赖库**：[marked@latest](https://marked.js.org/)
+- **兼容性**：现代浏览器（ES6+ 支持）
+
+--- 
+
+📌 **文档版本**：v1.0  
+📅 **最后更新**：2025年4月5日
\ No newline at end of file
diff --git a/aidocs/menu.md b/aidocs/menu.md
new file mode 100644
index 0000000..475f819
--- /dev/null
+++ b/aidocs/menu.md
@@ -0,0 +1,367 @@
+# `bricks.Menu` 技术文档
+
+> 本文档为 `bricks.Menu` 类的详细说明，基于其继承自 `bricks.VBox` 的结构和功能设计。
+
+---
+
+## 概述
+
+`bricks.Menu` 是一个用于构建可交互菜单界面组件的类，继承自 `bricks.VBox`。它支持嵌套子菜单、动态加载远程子菜单内容，并能响应菜单项点击事件以打开新窗口或更新目标组件内容。
+
+该组件适用于构建侧边栏菜单、导航菜单或任何树形结构的交互式 UI。
+
+---
+
+## 继承关系
+
+- **父类**: `bricks.VBox`
+- **类型**: 自定义 UI 组件类（Class-based）
+
+---
+
+## 构造函数
+
+```js
+constructor(options)
+```
+
+### 参数
+
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `options` | Object | 配置选项对象，继承自 `VBox` 并扩展以下属性 |
+
+#### `options` 支持字段：
+
+| 字段 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `items` | Array | ✅ | - | 菜单项数组，每个元素是一个菜单项配置对象（见下文） |
+| `bgcolor` | String | ❌ | `"white"` | 背景颜色 |
+| `target` | String | ❌ | - | 点击菜单项后内容加载的目标组件 ID 或特殊值 `'PopupWindow'` / `'Popup'` |
+| `popup_options` | Object | ❌ | `{}` | 当目标为 PopupWindow 或 Popup 时使用的弹窗配置 |
+
+> ⚠️ 注意：`target` 和 `popup_options` 可在单个菜单项中覆盖。
+
+### 示例
+
+```js
+new bricks.Menu({
+  items: [
+    { label: "首页", url: "/home" },
+    { label: "用户管理", submenu: "/api/users" }
+  ],
+  target: "main_content",
+  bgcolor: "#f5f5f5"
+});
+```
+
+---
+
+## 核心方法
+
+### `create_submenu_container()`
+
+创建一个用于容纳子菜单的容器（`VBox`），默认隐藏并带有缩进样式。
+
+#### 返回值
+
+- `{bricks.VBox}` —— 已配置好样式的子菜单容器
+
+#### 样式设置
+
+- `marginLeft: "15px"`
+- `display: "none"`
+
+---
+
+### `async menu_clicked(event)`
+
+处理菜单项被点击后的逻辑，根据配置打开页面、弹窗或注入到指定组件。
+
+#### 参数
+
+- `event`: DOM 事件对象，包含 `params` 字段，即菜单项数据。
+
+#### 行为逻辑
+
+1. 解析目标类型：
+   - 若 `target === 'PopupWindow'`：创建 `PopupWindow` 实例
+   - 若 `target === 'Popup'`：创建 `Popup` 实例
+   - 否则：查找对应 ID 的组件 (`bricks.getWidgetById`)
+2. 使用 `widgetBuild` 动态生成 URL Widget 并插入目标组件
+3. 触发全局 `command` 事件，携带原始菜单项参数
+
+#### 触发事件
+
+- `command`：携带菜单项信息，可用于外部监听执行命令
+
+#### 日志输出
+
+- 失败时打印错误日志：
+  - 目标组件未找到
+  - widget 构建失败
+
+---
+
+### `create_children(w, items)`
+
+递归创建菜单项及其子菜单。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `w` | `bricks.Container` | 容器组件，用于添加生成的菜单项 |
+| `items` | Array | 菜单项列表 |
+
+#### 子菜单类型判断
+
+| 条件 | 类型 | 说明 |
+|------|------|------|
+| `item.items` 存在 | 静态子菜单 | 直接递归创建 |
+| `item.submenu` 存在 | 动态子菜单 | 点击时通过 URL 加载 |
+| 其他 | 叶节点菜单项 | 绑定点击事件触发 `item_click` |
+
+#### 内部行为
+
+- 创建 `HBox` 表示菜单项
+- 添加图标与文本
+- 绑定点击/展开事件
+- 支持国际化（i18n）、换行、左对齐等文本特性
+
+---
+
+### `async get_submenu_items(url)`
+
+从远程 URL 获取子菜单数据（JSON 格式）。
+
+#### 参数
+
+- `url` (String): 请求地址
+
+#### 返回值
+
+- `Promise<Array>`: 菜单项数组（`data.options.items`）
+
+#### 示例响应格式
+
+```json
+{
+  "options": {
+    "items": [
+      { "label": "子项1", "url": "/sub1" },
+      { "label": "子项2", "url": "/sub2" }
+    ]
+  }
+}
+```
+
+---
+
+### `async load_submenu(container, event)`
+
+懒加载动态子菜单内容。
+
+#### 参数
+
+- `container`: 子菜单容器（`VBox`）
+- `event`: 点击事件
+
+#### 流程
+
+1. 阻止事件冒泡
+2. 若未加载过，则调用 `get_submenu_items()` 获取数据
+3. 调用 `create_children()` 填充内容
+4. 切换显示/隐藏状态
+
+> ✅ 实现“点击展开 → 首次加载 → 缓存”机制
+
+---
+
+### `items_toggle_hide(w, event)`
+
+切换静态子菜单的可见性。
+
+#### 参数
+
+- `w`: 子菜单容器
+- `event`: 事件对象
+
+#### 行为
+
+- 执行 `toggle_hide()` 显示或隐藏
+- 阻止事件冒泡
+
+---
+
+### `create_menuitem(item)`
+
+创建单个菜单项 UI 组件（`HBox`）。
+
+#### 参数
+
+- `item`: 菜单项配置对象
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `label` | String | 显示文本（支持 i18n） |
+| `icon` | String | 图标 URL |
+| `url` | String | 导航链接 |
+| `name` | String | 名称（备用标题） |
+| 其他字段 | Any | 将直接挂载到返回的 widget 上 |
+
+#### 返回值
+
+- `{bricks.HBox}` 包含图标和文本的水平布局组件
+
+#### 子组件
+
+| 组件 | 类型 | 说明 |
+|------|------|------|
+| `iw` | `Icon` 或 `BlankIcon` | 图标区域，若无图标则占位 |
+| `tw` | `Text` | 文本标签，启用自动换行、左对齐、填充样式 |
+
+#### 样式类
+
+- 应用 CSS 类名：`menuitem_css` 或默认 `'menuitem'`
+
+---
+
+### `regen_menuitem_event(item, event)`
+
+菜单项点击事件处理器，用于非容器型菜单项。
+
+#### 行为
+
+- 记录日志
+- 触发 `item_click` 事件并传递 `item`
+- 阻止事件冒泡
+
+---
+
+## 事件系统
+
+### 监听的事件
+
+- `item_click`: 当菜单项被点击时触发，由 `regen_menuitem_event` 发出
+
+### 分发的事件
+
+| 事件名 | 数据 | 说明 |
+|--------|------|------|
+| `item_click` | `item` 对象 | 内部使用，通知上级处理点击 |
+| `command` | `item` 对象 | 外部可监听，表示一个命令被执行 |
+
+---
+
+## 配置与扩展
+
+### 默认弹窗选项获取
+
+- `bricks.get_popupwindow_default_options()`
+- `bricks.get_popup_default_options()`
+
+可通过 `popup_options` 合并自定义配置（使用 `bricks.extend`）
+
+### 国际化支持
+
+- `Text` 组件启用 `i18n: true`，支持多语言翻译
+
+### 样式定制
+
+- 可通过 `menuitem_css` 自定义菜单项样式类
+- 使用 `set_css()` 和 `set_style()` 进行细粒度控制
+
+---
+
+## 注册与工厂模式
+
+```js
+bricks.Factory.register('Menu', bricks.Menu);
+```
+
+允许通过字符串标识符创建实例：
+
+```js
+bricks.createWidget("Menu", options);
+```
+
+---
+
+## 使用场景示例
+
+### 场景 1：静态树形菜单
+
+```js
+const menu = new bricks.Menu({
+  items: [
+    {
+      label: "仪表盘",
+      icon: "/icons/dashboard.png",
+      url: "/dashboard"
+    },
+    {
+      label: "设置",
+      items: [
+        { label: "账户", url: "/settings/account" },
+        { label: "安全", url: "/settings/security" }
+      ]
+    }
+  ],
+  target: "main_panel"
+});
+```
+
+### 场景 2：动态加载子菜单
+
+```js
+const menu = new bricks.Menu({
+  items: [
+    {
+      label: "产品分类",
+      submenu: "/api/categories",
+      icon: "/icons/folder.png"
+    }
+  ],
+  target: "PopupWindow",
+  popup_options: {
+    width: 800,
+    height: 600
+  }
+});
+```
+
+---
+
+## 注意事项
+
+1. **性能优化**：动态子菜单仅在首次展开时请求数据，后续展开直接显示缓存内容。
+2. **事件隔离**：所有点击事件均调用 `stopPropagation()` 防止意外冒泡。
+3. **URL Widget 构建**：依赖 `bricks.widgetBuild()` 异步构建，需确保环境已初始化。
+4. **目标组件存在性**：应确保 `target` 所指组件已注册且可用。
+
+---
+
+## 依赖模块
+
+| 模块 | 用途 |
+|------|------|
+| `bricks.VBox`, `bricks.HBox` | 布局容器 |
+| `bricks.Icon`, `bricks.BlankIcon` | 图标显示 |
+| `bricks.Text` | 文本渲染与 i18n |
+| `bricks.PopupWindow`, `bricks.Popup` | 弹窗组件 |
+| `bricks.HttpJson` | JSON 数据请求 |
+| `bricks.Factory`, `bricks.widgetBuild` | 组件工厂与异步构建 |
+| `bricks.extend` | 对象合并工具函数 |
+
+---
+
+## 版本信息
+
+- **作者**: Bricks Framework Team
+- **版本**: v1.0（基础功能稳定）
+- **最后更新**: 2025年4月5日
+
+--- 
+
+✅ *本组件适用于构建灵活、可扩展的菜单系统，推荐结合路由系统或 CMS 后台使用。*
\ No newline at end of file
diff --git a/aidocs/message.md b/aidocs/message.md
new file mode 100644
index 0000000..b59681f
--- /dev/null
+++ b/aidocs/message.md
@@ -0,0 +1,218 @@
+# `bricks.Message` 与 `bricks.Error` 技术文档
+
+> 基于 Bricks UI 框架的消息弹窗组件
+
+---
+
+## 概述
+
+`bricks.Message` 和 `bricks.Error` 是基于 `bricks.PopupWindow` 构建的轻量级消息提示组件，用于在 Web 应用中显示文本信息或错误提示。该模块提供统一的 API 接口（`bricks.show_message` 和 `bricks.show_error`），便于快速调用。
+
+- `bricks.Message`：通用消息弹窗。
+- `bricks.Error`：专用于显示错误信息的弹窗，样式上更突出。
+- 支持国际化（i18n）、自动换行、居中对齐等特性。
+
+---
+
+## 继承结构
+
+```
+bricks.PopupWindow
+    └── bricks.Message
+            └── bricks.Error
+```
+
+---
+
+## 类定义
+
+### `bricks.Message`
+
+继承自 `bricks.PopupWindow`，用于创建可配置的消息提示窗口。
+
+#### 构造函数
+
+```js
+new bricks.Message(opts)
+```
+
+##### 参数
+
+| 参数 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `opts` | Object | ✅ | 配置选项对象 |
+
+###### `opts` 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `title` | String | - | 弹窗标题 |
+| `message` | String | - | 要显示的消息正文内容 |
+| `auto_open` | Boolean | `true` | 是否在构造后自动打开窗口（由构造函数内部设置） |
+| `cheight` | Number | `9` | 内容区域高度（单位：网格） |
+| `cwidth` | Number | `16` | 内容区域宽度（单位：网格） |
+
+> ⚠️ 注意：`auto_open` 在构造函数中被强制设为 `true`，因此所有 `Message` 实例创建后会立即显示。
+
+#### 方法
+
+##### `create_message_widget()`
+
+私有方法，负责构建消息内容区域的 UI 结构。
+
+**UI 结构如下：**
+
+```
+Filler (填充容器)
+└── VScrollPanel (垂直滚动面板)
+    └── Text (文本控件，支持换行和居中)
+```
+
+- 使用 `bricks.Filler` 作为内容填充层。
+- 使用 `bricks.VScrollPanel` 包裹文本以支持长文本滚动。
+- 使用 `bricks.Text` 显示消息，启用：
+  - 自动换行 (`wrap: true`)
+  - 水平居中对齐 (`halign: 'middle'`)
+  - 国际化支持 (`i18n: true`)
+
+##### `set_css(cssClass)`
+
+设置弹窗的 CSS 样式类前缀为 `'message'`，用于应用主题样式。
+
+---
+
+### `bricks.Error`
+
+继承自 `bricks.Message`，专用于显示错误信息。
+
+#### 构造函数
+
+```js
+new bricks.Error(opts)
+```
+
+##### 参数
+
+同 `bricks.Message` 的 `opts`。
+
+##### 行为差异
+
+- 调用父类构造函数（即 `super(opts)`）完成初始化。
+- 额外调用 `this.set_css('error')`，将样式类切换为 `'error'`，通常表现为红色边框/背景等视觉警示。
+
+---
+
+## 全局快捷函数
+
+### `bricks.show_message(opts)`
+
+快速显示一条普通消息。
+
+```js
+bricks.show_message({
+    title: "提示",
+    message: "操作已成功完成。"
+});
+```
+
+#### 参数
+
+同 `bricks.Message` 的 `opts`。
+
+> 若未指定 `cheight` 或 `cwidth`，则默认使用 `9` 和 `16`。
+
+---
+
+### `bricks.show_error(opts)`
+
+快速显示一条错误消息。
+
+```js
+bricks.show_error({
+    title: "出错了",
+    message: "无法连接到服务器，请检查网络。"
+});
+```
+
+#### 参数
+
+同 `bricks.Message` 的 `opts`。
+
+> 视觉样式通过 `set_css('error')` 强化，适合错误场景。
+
+---
+
+## 工厂注册
+
+为支持动态创建机制，两类组件已在 `bricks.Factory` 中注册：
+
+```js
+bricks.Factory.register('Message', bricks.Message);
+bricks.Factory.register('Error', bricks.Error);
+```
+
+这意味着可以通过工厂模式按名称实例化这些组件：
+
+```js
+var msg = bricks.Factory.create('Message', { title: "Hello", message: "World" });
+```
+
+---
+
+## 使用示例
+
+### 显示普通消息
+
+```js
+bricks.show_message({
+    title: "欢迎",
+    message: "欢迎使用 Bricks 框架！这是一个示例消息。",
+    cheight: 10,
+    cwidth: 20
+});
+```
+
+### 显示错误消息
+
+```js
+bricks.show_error({
+    title: "加载失败",
+    message: "请求的数据未能获取，请稍后再试。长时间失败请联系管理员。",
+    cheight: 12
+});
+```
+
+---
+
+## 样式说明
+
+| 组件 | CSS Class 前缀 | 典型用途 |
+|------|----------------|----------|
+| `bricks.Message` | `.message-*` | 一般通知、提示 |
+| `bricks.Error`   | `.error-*`   | 错误、警告信息 |
+
+开发者应在 CSS 中定义相应的样式规则以实现美观的视觉效果。
+
+---
+
+## 依赖项
+
+确保以下组件已加载：
+
+- `bricks.PopupWindow`
+- `bricks.Filler`
+- `bricks.VScrollPanel`
+- `bricks.Text`
+- `bricks.Factory`
+
+---
+
+## 版本信息
+
+- 创建时间：未知
+- 框架版本：Bricks UI（假设）
+- 作者：Bricks 团队 / 开发者社区
+
+--- 
+
+✅ **推荐使用 `bricks.show_message()` 和 `bricks.show_error()` 快捷函数进行调用，避免手动管理窗口生命周期。**
\ No newline at end of file
diff --git a/aidocs/miniform.md b/aidocs/miniform.md
new file mode 100644
index 0000000..caa815c
--- /dev/null
+++ b/aidocs/miniform.md
@@ -0,0 +1,314 @@
+# `bricks.MiniForm` 技术文档
+
+> **MiniForm** 是一个基于 `bricks.HBox` 的轻量级表单组件，用于动态切换和输入不同字段的数据。它支持通过下拉选择器快速切换输入项，并实时触发输入事件。
+
+---
+
+## 概述
+
+`bricks.MiniForm` 类继承自 `bricks.HBox`，提供了一个紧凑的表单界面，适用于需要在多个输入字段之间快速切换的场景（如搜索框、参数配置等）。该组件包含：
+
+- 一个下拉选择器（用于选择当前字段）
+- 一个动态输入控件（根据所选字段类型自动创建）
+- 支持自定义字段属性和默认值
+- 可扩展的输入事件机制
+
+---
+
+## 继承关系
+
+```
+bricks.HBox
+    └── bricks.MiniForm
+```
+
+---
+
+## 构造函数
+
+```js
+new bricks.MiniForm(options)
+```
+
+### 参数
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| `options` | Object | ✅ | 配置对象，结构如下 |
+
+#### `options` 结构
+
+| 属性 | 类型 | 必填 | 默认值 | 描述 |
+|------|------|------|--------|------|
+| `defaultname` | String | ❌ | 第一个字段的 `name` | 默认激活的字段名称 |
+| `label_width` | String/Number | ❌ | - | 标签列宽度（可被字段级覆盖） |
+| `input_width` | String/Number | ❌ | - | 输入框宽度（可被字段级覆盖） |
+| `params` | Object | ❌ | `{}` | 固定附加参数，在 `getValue()` 中返回 |
+| `fields` | Array&lt;Object&gt; | ✅ | - | 字段定义数组，每个字段包含以下子属性 |
+
+##### `fields[i]` 字段定义
+
+| 属性 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `name` | String | ✅ | 字段唯一标识符（如：`"username"`） |
+| `label` | String | ✅ | 显示名称（出现在下拉列表中） |
+| `icon` | String | ❌ | 图标类名（可选，用于视觉增强） |
+| `uitype` | String | ✅ | 控件类型（如 `"text"`, `"number"`, `"code"` 等），需与 `Input.factory` 兼容 |
+| `uiparams` | Object | ❌ | 传递给具体输入控件的额外配置参数 |
+
+---
+
+## 示例配置
+
+```js
+var miniForm = new bricks.MiniForm({
+    defaultname: 'email',
+    params: { action: 'search' },
+    fields: [
+        {
+            name: 'username',
+            label: '用户名',
+            uitype: 'text',
+            uiparams: { placeholder: '请输入用户名' }
+        },
+        {
+            name: 'email',
+            label: '邮箱',
+            uitype: 'text',
+            uiparams: { type: 'email', placeholder: '请输入邮箱' }
+        },
+        {
+            name: 'count',
+            label: '数量',
+            uitype: 'number',
+            uiparams: { min: 1, max: 100 }
+        }
+    ]
+});
+```
+
+---
+
+## 方法说明
+
+### `constructor(opts)`
+
+初始化 MiniForm 实例并调用 `build()`。
+
+#### 行为：
+- 设置容器宽高为 `'auto'`
+- 调用父类构造函数
+- 执行 `build()` 构建 UI
+
+---
+
+### `build()`
+
+构建整个组件的 UI，包括选项选择器和初始输入控件。
+
+#### 步骤：
+1. 确定默认字段名（优先使用 `defaultname`，否则取第一个字段）
+2. 调用 `build_options()` 创建下拉选择器
+3. 调用 `build_widgets(name)` 初始化对应输入控件
+
+---
+
+### `build_options()`
+
+创建一个下拉选择控件（`this.choose`），允许用户切换当前编辑的字段。
+
+#### 使用 `Input.factory` 创建的选择器配置：
+```js
+{
+    width: "90px",
+    name: "name",
+    uiType: "code", // 假设为下拉或代码选择器
+    valueField: 'name',   // 绑定值为字段的 name
+    textField: 'label',   // 显示文本为 label
+    data: this.opts.fields
+}
+```
+
+> ⚠️ 注：`uiType: "code"` 可能表示一种特殊下拉控件，实际应确保其行为符合预期（例如 ComboBox 或 Select）。
+
+绑定事件：`changed` → `change_input(e)`
+
+---
+
+### `build_widgets(name)`
+
+根据指定字段名动态创建对应的输入控件。
+
+#### 参数：
+- `name`: 字段名（必须存在于 `fields` 中）
+
+#### 流程：
+1. 若已有输入控件，则解绑 `input` 事件
+2. 清空当前所有控件
+3. 添加选择器控件 `this.choose`
+4. 查找匹配字段定义 `f`
+5. 复制字段描述并设置 `width: 'auto'`
+6. 使用 `Input.factory(desc)` 创建输入控件 `i`
+7. 绑定 `input` 事件到 `input_handle`
+8. 将新控件加入布局
+9. 保存引用至 `this.input`
+
+---
+
+### `change_input(e)`
+
+当下拉选择器值改变时触发，重新构建输入控件。
+
+#### 行为：
+- 获取当前选择的字段名 `this.choose.value`
+- 调用 `build_widgets(name)` 切换输入控件
+
+---
+
+### `input_handle(e)`
+
+当输入内容发生变化时触发，用于广播事件。
+
+#### 行为：
+1. 调用 `getValue()` 获取完整数据
+2. 输出调试信息（通过 `bricks.debug`）
+3. 触发 `input` 事件，携带数据 `d`
+
+```js
+this.dispatch('input', d);
+```
+
+> 可通过 `.bind('input', handler)` 监听此事件
+
+---
+
+### `getValue() → Object`
+
+获取当前表单的合并值。
+
+#### 返回值结构：
+```js
+{
+    // 来自 this.opts.params 的固定参数
+    action: 'search',
+    // 来自当前输入控件的动态值
+    username: 'john_doe'
+}
+```
+
+#### 逻辑：
+- 初始化为 `params` 对象（若未设置则为空 `{}`）
+- 合并当前输入控件的值（`this.input.getValue()`）
+- 使用 `bricks.extend(d, v)` 进行浅合并
+
+---
+
+### `show_options(e)`
+
+显示下拉选择器（调试用途或外部调用）。
+
+#### 行为：
+- 输出调试日志
+- 调用 `this.choose.show()` 显示选择器
+
+> 主要用于开发调试或定制交互逻辑
+
+---
+
+### `clear_widgets()`
+
+> 📌 注意：此方法未在代码中定义，但被调用。
+
+假设其来自父类 `HBox`，功能为清空所有子控件。
+
+---
+
+## 事件系统
+
+### 支持监听的事件
+
+| 事件名 | 触发时机 | 携带数据 |
+|--------|----------|---------|
+| `input` | 输入值变化时 | 合并后的表单数据对象 |
+
+#### 示例监听：
+
+```js
+miniForm.bind('input', function(data) {
+    console.log('Current form data:', data);
+    // { action: 'search', username: 'testuser' }
+});
+```
+
+---
+
+## 工厂注册
+
+```js
+bricks.Factory.register('MiniForm', bricks.MiniForm);
+```
+
+允许通过工厂模式创建实例：
+
+```js
+var form = bricks.Factory.create('MiniForm', options);
+```
+
+---
+
+## 设计特点
+
+| 特性 | 说明 |
+|------|------|
+| ✅ 动态输入切换 | 支持运行时更换输入控件类型 |
+| ✅ 模块化结构 | 基于 `Input.factory` 实现控件解耦 |
+| ✅ 可扩展性 | 支持任意 `uitype` 和 `uiparams` |
+| ✅ 事件驱动 | 提供标准 `input` 事件接口 |
+| ⚠️ 宽度控制有限 | 当前 `label_width` / `input_width` 未完全实现（可能依赖样式或其他机制） |
+
+---
+
+## 注意事项
+
+1. **`Input.factory` 依赖**  
+   必须确保 `Input.factory` 支持所有声明的 `uitype` 类型。
+
+2. **`objcopy()` 函数**  
+   代码中使用了 `objcopy(f)`，应确保全局存在此工具函数（通常为对象深拷贝或浅拷贝）。
+
+3. **`bricks.extend`**  
+   用于合并对象，类似 jQuery 的 `$.extend` 或 Lodash 的 `_.assign`。
+
+4. **UI 渲染顺序**  
+   每次切换字段都会重建输入控件，适合字段较少的场景；高频切换可能影响性能。
+
+5. **样式兼容性**  
+   推荐配合 CSS 设置 `.bricks-miniform` 或相关类以优化布局。
+
+---
+
+## 调试支持
+
+启用调试模式后，会输出以下信息：
+
+- `show_options()` 调用记录
+- `input_handle()` 中的实时数据
+
+可通过 `bricks.debug = console.log` 启用。
+
+---
+
+## 总结
+
+`bricks.MiniForm` 是一个简洁高效的动态表单组件，特别适用于：
+
+- 多条件搜索栏
+- 快捷参数输入
+- 动态配置面板
+
+结合 `bricks` 框架的输入控件体系，能够快速搭建灵活的用户界面。
+
+--- 
+
+✅ **推荐使用场景**：工具条、查询过滤器、快捷操作面板  
+🔧 **可优化方向**：缓存输入控件实例、支持更多布局配置、增加验证机制
\ No newline at end of file
diff --git a/aidocs/modal.md b/aidocs/modal.md
new file mode 100644
index 0000000..13bdb3d
--- /dev/null
+++ b/aidocs/modal.md
@@ -0,0 +1,295 @@
+# `bricks` 模态组件技术文档
+
+> **版本：1.0**  
+> **模块：Modal, BaseModal, ModalForm**
+
+本文档描述了 `bricks` 框架中与模态窗口相关的类，包括 `BaseModal`、`Modal` 和 `ModalForm`。这些类用于创建可重用的弹出层（Modal）组件，支持自定义定位、样式、自动关闭、超时关闭等功能。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [核心类结构](#核心类结构)
+- [`bricks.BaseModal`](#bricksbasemodal)
+  - [构造函数参数](#构造函数参数-base-modal)
+  - [属性](#属性-base-modal)
+  - [方法](#方法-base-modal)
+- [`bricks.Modal`](#bricksmodal)
+  - [构造函数参数](#构造函数参数-modal)
+  - [属性](#属性-modal)
+  - [方法](#方法-modal)
+- [`bricks.ModalForm`](#bricksmodalfom)
+  - [构造函数参数](#构造函数参数-modalfom)
+  - [属性](#属性-modalfom)
+  - [方法](#方法-modalfom)
+- [注册与使用](#注册与使用)
+- [示例代码](#示例代码)
+
+---
+
+## 概述
+
+`bricks` 提供了一套基于布局系统的模态对话框系统：
+
+- `BaseModal` 是所有模态组件的基础类。
+- `Modal` 是一个带标题栏和内容区域的标准模态窗口。
+- `ModalForm` 是一个用于展示表单的模态窗口，集成 `Form` 组件并处理提交逻辑。
+- 所有模态窗口通过 Z-index 管理堆叠顺序，并支持锚点对齐（`archor`）、目标容器绑定等特性。
+
+---
+
+## 核心类结构
+
+```text
+bricks.Layout
+└── bricks.BaseModal
+    ├── bricks.Modal
+    └── bricks.ModalForm (extends PopupWindow)
+```
+
+> 注意：`ModalForm` 实际继承自 `PopupWindow` 而非 `Modal`，但功能上属于模态系列组件。
+
+---
+
+## `bricks.BaseModal`
+
+基础模态类，提供通用的模态行为，如显示/隐藏、Z-index 控制、目标挂载等。
+
+### 构造函数参数 (Base Modal)
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `target` | `string` 或 `Layout` | 模态窗口挂载的目标容器。字符串表示 ID，对象为 Layout 实例。默认为 `bricks.Body`。 |
+| `auto_open` | `boolean` | 是否在添加子组件后自动打开模态。 |
+| `auto_close` | `boolean` | （未启用）是否点击背景关闭模态。 |
+| `org_index` | `number` | 初始 z-index 值（暂未使用）。 |
+| `width` | `string` | 内容面板宽度（如 `'500px'`, `'80%'`）。 |
+| `height` | `string` | 内容面板高度。 |
+| `bgcolor` | `string` | 内容面板背景色，默认 `#e8e8e8`。 |
+| `title` | `string` | 标题文本（仅被 `Modal` 使用）。 |
+| `timeout` | `number` | 自动关闭延迟时间（毫秒），0 表示不自动关闭。 |
+| `archor` | `string` | 锚点位置，控制内容居中方式：<br>`tl`, `tc`, `tr`, `cl`, `cc`, `cr`, `bl`, `bc`, `br`<br>默认值：`'cc'`（居中） |
+
+### 属性 (Base Modal)
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `panel` | `VBox` | 实际内容容器，内部垂直布局。 |
+| `timeout` | `number` | 自动关闭延时（ms）。 |
+| `timeout_task` | `Task` | 定时任务句柄，用于取消定时关闭。 |
+| `target_w` | `Layout` | 解析后的目标挂载容器。 |
+| `ancestor_add_widget` | `Function` | 保存父类 `add_widget` 方法的引用。 |
+
+### 方法 (Base Modal)
+
+#### `create()`
+创建模态外层 DOM 元素：
+- 使用 `<div>` 作为遮罩层。
+- 设置 `position: fixed` 遮罩全屏。
+- 背景颜色为半透明黑色 (`rgba(0,0,0,0.4)`)。
+- 初始隐藏（`display: none`）。
+- 自动分配递增的 `z-index`。
+
+#### `get_zindex() → number`
+获取下一个可用的 `z-index` 值，从 `bricks.min_zindex` 开始递增。
+
+> 默认起始值：`5000`
+
+#### `add_widget(widget, index)`
+向 `panel` 添加子控件。如果设置了 `auto_open: true`，则立即调用 `open()`。
+
+#### `open()`
+显示模态窗口：
+- 将 `dom_element.style.display` 设为空字符串（即显示）。
+- 若设置了 `timeout > 0`，启动延迟关闭任务。
+- 触发 `opened` 事件。
+
+#### `dismiss()`
+关闭并移除模态窗口：
+- 隐藏元素。
+- 取消超时任务。
+- 从父容器中移除自身。
+- 触发 `dismissed` 事件。
+- 异常捕获防止中断。
+
+---
+
+## `bricks.Modal`
+
+标准模态对话框，继承自 `BaseModal`，带有可关闭标题栏。
+
+### 构造函数参数 (Modal)
+
+同 `BaseModal`，额外支持：
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `title` | `string` | 显示在标题栏中的文字。 |
+
+### 属性 (Modal)
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `title_box` | `HBox` | 水平布局的标题栏容器。 |
+| `title_w` | `Filler` | 标题文本占位容器。 |
+| `content` | `Filler` | 主体内容容器，填充剩余空间。 |
+
+### 方法 (Modal)
+
+#### `create_title()`
+创建标题栏：
+- 包含一个水平盒子 `HBox`。
+- 左侧显示标题文本（使用 `Text` 组件，支持国际化 `i18n` 和动态尺寸 `dynsize`）。
+- 右侧放置关闭图标（SVG 图标，绑定 `click → dismiss()`）。
+- 添加 CSS 类名 `title`。
+
+#### `add_widget(widget, index)`
+将组件添加到 `content` 区域。若 `auto_open` 为真，则自动打开模态。
+
+#### `click_handler(event)`
+点击事件处理器（当前注释状态）：
+- 如果点击的是模态遮罩层（非内容区域），触发 `dismiss()`。
+- 用于实现“点击背景关闭”功能（目前未启用）。
+
+> ⚠️ 当前该功能已被注释，需手动启用。
+
+---
+
+## `bricks.ModalForm`
+
+用于快速弹出表单的模态窗口，集成异步表单构建和提交处理。
+
+### 构造函数参数 (ModalForm)
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `title` | `string` | 表单标题。 |
+| `description` | `string` | 表单描述信息。 |
+| `fields` | `Array<FieldOptions>` | 表单字段定义数组。 |
+| `binds` | `Array<BindConfig>` | 数据绑定配置。 |
+| `user_data` | `any` | 用户自定义数据（可选）。 |
+| `submit_url` | `string` | 提交 URL（可通过实例设置）。 |
+| 其他 | 同 `PopupWindow` | 如 `width`, `height`, `archor` 等。 |
+
+### 属性 (ModalForm)
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `form` | `Form` | 动态生成的表单实例。 |
+| `submit_url` | `string` | 表单提交地址（可选）。 |
+
+### 方法 (ModalForm)
+
+#### `build_form() → Promise<void>`
+异步构建表单：
+- 延迟 200ms 执行（确保 DOM 就绪）。
+- 使用 `bricks.widgetBuild()` 动态创建 `Form` 组件。
+- 添加至模态内容区。
+- 绑定以下事件：
+  - `submit`: 触发 `form_submit`
+  - `submited`: 转发服务器响应
+  - `cancel`: 关闭模态
+- 最后调用 `open()` 显示。
+
+#### `_getValue() → any`
+获取原始表单数据（未经格式化）。
+
+#### `getValue() → any`
+获取经过验证和处理的表单数据。
+
+#### `form_submit()`
+处理表单提交：
+- 获取数据并派发 `submit` 事件。
+- 立即关闭模态（`dismiss()`）。
+
+#### `form_submited(event)`
+当表单成功提交后，转发 `submited` 事件及其参数。
+
+---
+
+## 注册与使用
+
+```js
+// 注册工厂类，便于通过字符串创建
+bricks.Factory.register('Modal', bricks.Modal);
+bricks.Factory.register('ModalForm', bricks.ModalForm);
+```
+
+这意味着你可以使用如下方式动态创建：
+
+```js
+let modal = bricks.Factory.create('Modal', { title: '提示', width: '400px' });
+```
+
+---
+
+## 示例代码
+
+### 创建一个简单模态窗口
+
+```js
+let modal = new bricks.Modal({
+  title: '欢迎',
+  width: '500px',
+  height: '300px',
+  auto_open: true,
+  archor: 'cc'
+});
+
+modal.add_widget(new bricks.Text({ otext: '这是模态内容！' }));
+```
+
+### 创建一个表单模态
+
+```js
+let formModal = new bricks.ModalForm({
+  title: '用户信息',
+  description: '请填写以下信息',
+  fields: [
+    { name: 'name', label: '姓名', type: 'text' },
+    { name: 'age', label: '年龄', type: 'number' }
+  ],
+  binds: [
+    ['name', 'user.name'],
+    ['age', 'user.age']
+  ]
+});
+
+formModal.bind('submit', function(data) {
+  console.log('提交数据:', data);
+});
+```
+
+---
+
+## 注意事项
+
+1. **Z-index 管理**：所有模态共享全局 `last_zindex` 计数器，确保新窗口总在最上层。
+2. **锚点定位**：依赖外部函数 `archorize(el, pos)` 实现元素定位，请确保其存在。
+3. **资源路径**：关闭图标使用 `bricks_resource('imgs/delete.svg')` 加载，需正确配置资源路径。
+4. **事件解绑**：`click_handler` 的绑定/解绑逻辑目前被注释，如需启用请解除注释并测试。
+
+---
+
+## 依赖说明
+
+- `bricks.Layout`, `bricks.VBox`, `bricks.HBox`, `bricks.Filler`, `bricks.Text`, `bricks.Svg` —— 布局与基础组件。
+- `bricks.widgetBuild()` —— 异步组件构建工具。
+- `schedule_once(fn, delay)` —— 延迟执行工具函数。
+- `objget(obj, key, default)` —— 安全取值工具。
+- `archorize(element, position)` —— 锚点定位函数。
+
+---
+
+✅ **建议用途**：适用于消息提示、确认框、登录弹窗、动态表单提交等场景。
+
+🔧 **扩展建议**：
+- 支持键盘 ESC 关闭。
+- 添加动画过渡效果。
+- 支持拖拽移动（针对 `ModalForm`）。
+
+--- 
+
+📖 *文档版本：1.0*  
+📅 *最后更新：2025年4月5日*
\ No newline at end of file
diff --git a/aidocs/multiple_state_image.md b/aidocs/multiple_state_image.md
new file mode 100644
index 0000000..937e556
--- /dev/null
+++ b/aidocs/multiple_state_image.md
@@ -0,0 +1,170 @@
+# `MultipleStateImage` 技术文档
+
+> **命名空间**: `bricks.MultipleStateImage`  
+> **继承自**: `bricks.Layout`  
+> **注册名称**: `'MultipleStateImage'`（可通过 `bricks.Factory` 创建）
+
+---
+
+## 概述
+
+`MultipleStateImage` 是一个可交互的图像组件，支持在多个预定义状态之间切换。每个状态对应一张不同的图片 URL。用户点击图像时，组件会自动切换到下一个状态，并更新显示的图片。
+
+该组件适用于需要通过点击切换不同视觉状态的场景，例如：开关按钮、多状态图标、轮播式图片控件等。
+
+---
+
+## 构造函数
+
+```js
+new bricks.MultipleStateImage(options)
+```
+
+### 参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|-------|------|------|------|
+| `opts` | `Object` | ✅ | 配置选项对象 |
+
+#### `opts` 配置项
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `state` | `String` | ✅ | 初始状态名称，必须是 `urls` 中的一个键 |
+| `urls` | `Object<String, String>` | ✅ | 状态与图片 URL 的映射表，格式为 `{ stateName: imageUrl }` |
+| `width` | `Number` \| `String` | ❌ | 图像宽度（可选，传递给内部 `bricks.Image` 组件） |
+| `height` | `Number` \| `String` | ❌ | 图像高度（可选，传递给内部 `bricks.Image` 组件） |
+
+---
+
+## 示例用法
+
+```js
+var image = new bricks.MultipleStateImage({
+    state: 'off',
+    urls: {
+        off: 'images/light_off.png',
+        on: 'images/light_on.png'
+    },
+    width: 100,
+    height: 100
+});
+
+// 添加到父容器
+parent.add_widget(image);
+
+// 监听状态变化
+image.bind('state_changed', function(newState) {
+    console.log('当前状态:', newState);
+});
+```
+
+---
+
+## 方法
+
+### `set_state(state)`
+
+手动设置当前状态并更新图像。
+
+- **参数**:
+  - `state` (`String`) - 要切换到的状态名，必须存在于 `opts.urls` 中。
+- **行为**:
+  - 更新内部状态 `this.state`
+  - 调用内部图像的 `set_url()` 方法加载新图片
+
+```js
+image.set_state('on');
+```
+
+---
+
+### `change_state(event)`
+
+**私有方法 / 事件处理器** — 响应图像点击事件，自动切换到下一个状态。
+
+- **触发方式**: 用户点击图像时自动调用
+- **行为**:
+  - 阻止事件冒泡（`stopPropagation`）
+  - 在 `urls` 的状态列表中循环切换至下一个状态
+  - 若已是最后一个状态，则回到第一个状态（循环切换）
+  - 触发 `state_changed` 事件
+
+> ⚠️ 通常无需直接调用此方法，已绑定在图像的 `'click'` 事件上。
+
+---
+
+## 事件
+
+### `state_changed`
+
+当图像状态发生改变时触发。
+
+- **回调参数**:
+  - `newState` (`String`) - 当前切换后的状态名
+
+```js
+image.bind('state_changed', function(state) {
+    console.log('状态已切换为:', state);
+});
+```
+
+---
+
+## 内部结构
+
+- 使用 `bricks.Image` 实例作为核心图像渲染组件
+- 将自身作为布局容器，通过 `add_widget(this.img)` 管理子组件
+- 状态切换逻辑基于 `Object.keys(this.opts.urls)` 的顺序进行循环
+
+---
+
+## 注意事项
+
+1. **状态顺序依赖对象键的枚举顺序**  
+   JavaScript 中对象属性的遍历顺序在现代引擎中通常是插入顺序，建议确保 `urls` 对象的键按预期顺序定义。
+
+2. **URL 合法性需提前校验**  
+   组件不检查图片 URL 是否有效，错误需由外部处理。
+
+3. **事件绑定自动完成**  
+   构造函数中已自动绑定 `'click'` 事件，无需重复绑定。
+
+4. **工厂注册**  
+   已通过 `bricks.Factory.register('MultipleStateImage', ...)` 注册，可在声明式模板中使用类型名创建。
+
+---
+
+## 工厂注册
+
+```js
+bricks.Factory.register('MultipleStateImage', bricks.MultipleStateImage);
+```
+
+允许通过配置方式创建实例：
+
+```js
+bricks.Factory.create({
+    type: 'MultipleStateImage',
+    state: 'off',
+    urls: {
+        off: 'images/off.png',
+        on: 'images/on.png'
+    },
+    width: 50,
+    height: 50
+});
+```
+
+---
+
+## 版权与归属
+
+- 所属模块: `bricks`
+- 组件名: `MultipleStateImage`
+- 作者: （根据项目上下文补充）
+- 版本: 1.0.0
+
+--- 
+
+✅ *文档结束*
\ No newline at end of file
diff --git a/aidocs/myoperator.md b/aidocs/myoperator.md
new file mode 100644
index 0000000..8a32fd0
--- /dev/null
+++ b/aidocs/myoperator.md
@@ -0,0 +1,117 @@
+# `Oper` 类技术文档
+
+## 概述
+
+`Oper` 是一个用于封装数值并支持自定义加法操作的 JavaScript 类。通过该类，可以创建包含数值的对象，并使用内置的方法执行对象间的加法运算。
+
+> **注意**：该类中定义了两个功能几乎相同的加法方法 `__plus__` 和 `__add__`，可能是为了兼容不同命名习惯或未来扩展预留。
+
+---
+
+## 构造函数
+
+### `constructor(v)`
+
+初始化一个 `Oper` 实例，将传入的值保存在 `value` 属性中。
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `v`  | `number` | 初始化的数值 |
+
+#### 示例
+```javascript
+const a = new Oper(5);
+console.log(a.value); // 输出: 5
+```
+
+---
+
+## 方法
+
+### `__plus__(a, b)`
+
+执行两个 `Oper` 对象的加法操作，返回一个新的 `Oper` 实例，其值为两个操作数 `value` 属性之和。该方法会输出两个操作数到控制台。
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `a`  | `Oper` | 第一个操作数 |
+| `b`  | `Oper` | 第二个操作数 |
+
+#### 返回值
+- 类型：`Oper`
+- 说明：一个新的 `Oper` 实例，其 `value` 为 `a.value + b.value`
+
+#### 示例
+```javascript
+const x = new Oper(3);
+const y = new Oper(7);
+const result = new Oper().__plus__(x, y);
+// 控制台输出: Oper { value: 3 }, Oper { value: 7 }
+console.log(result.value); // 输出: 10
+```
+
+---
+
+### `__add__(a, b)`
+
+与 `__plus__` 功能完全相同，执行两个 `Oper` 对象的加法操作并返回新实例，同时打印操作数到控制台。
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `a`  | `Oper` | 第一个操作数 |
+| `b`  | `Oper` | 第二个操作数 |
+
+#### 返回值
+- 类型：`Oper`
+- 说明：一个新的 `Oper` 实例，其 `value` 为 `a.value + b.value`
+
+#### 示例
+```javascript
+const m = new Oper(4);
+const n = new Oper(6);
+const sum = new Oper().__add__(m, n);
+// 控制台输出: Oper { value: 4 }, Oper { value: 6 }
+console.log(sum.value); // 输出: 10
+```
+
+---
+
+## 注意事项
+
+1. 所有方法均为实例方法，调用时需要先创建 `Oper` 实例。
+2. `__plus__` 和 `__add__` 行为一致，可能存在冗余，建议根据实际需求保留其一或用于不同语义场景。
+3. 当前实现未做类型检查，若传入非 `Oper` 实例或 `value` 非数字，可能导致运行时错误。
+4. 方法设计为静态操作风格（接受两个操作数），而非基于当前实例的 `this.value` 进行计算，这可能与常规面向对象设计不符，使用时需注意。
+
+---
+
+## 建议改进
+
+```js
+// 改进建议：基于实例的加法
+class Oper {
+  constructor(v) {
+    this.value = v;
+  }
+
+  add(other) {
+    return new Oper(this.value + other.value);
+  }
+}
+
+// 使用方式更自然
+const a = new Oper(5);
+const b = new Oper(3);
+const c = a.add(b);
+console.log(c.value); // 8
+```
+
+--- 
+
+## 版本信息
+
+- 语言：JavaScript (ES6+)
+- 兼容性：现代浏览器及 Node.js 环境
\ No newline at end of file
diff --git a/aidocs/myvad.md b/aidocs/myvad.md
new file mode 100644
index 0000000..9971148
--- /dev/null
+++ b/aidocs/myvad.md
@@ -0,0 +1,164 @@
+# VAD（语音活动检测）模块技术文档
+
+> **基于 `@ricky0912/vad-web` 的 Web 端语音活动检测集成方案**
+
+---
+
+## 概述
+
+本模块提供了一个轻量级的语音活动检测（Voice Activity Detection, VAD）功能封装，用于在浏览器环境中实时检测用户语音的开始与结束，并在语音结束后回调处理音频数据。该模块依赖于 [`vad-web`](https://www.npmjs.com/package/@ricky0123/vad-web) 库，底层使用 ONNX Runtime Web 实现高性能推理。
+
+主要功能：
+- 实时麦克风音频采集
+- 自动检测语音段（Speech Segment）
+- 在语音结束后触发回调，返回 `Float32Array` 格式的 16kHz 音频样本
+- 支持动态启用/禁用 VAD
+
+---
+
+## 依赖引入
+
+```html
+<!-- 引入 ONNX Runtime Web（VAD 依赖） -->
+<script src="https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/ort.js"></script>
+
+<!-- 引入 vad-web 库 -->
+<script src="https://cdn.jsdelivr.net/npm/@ricky0123/vad-web@0.0.7/dist/bundle.min.js"></script>
+```
+
+> ⚠️ 注意：必须按顺序加载 `ort.js` 后再加载 `vad-web`，否则会报错。
+
+---
+
+## API 接口
+
+### `bricks.enable_vad(func)`
+
+启动语音活动检测，并设置语音结束时的回调函数。
+
+#### 参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `func` | `Function` | 回调函数，接收一个参数 `audio`，类型为 `Float32Array`，表示采样率为 16000Hz 的单声道音频数据 |
+
+#### 示例
+
+```javascript
+bricks.enable_vad(function(audio) {
+  console.log("语音结束，音频长度:", audio.length);
+  // 可将 audio 发送到后端进行 ASR 识别等处理
+});
+```
+
+#### 内部实现
+
+```javascript
+bricks.vad = await vad.MicVAD.new({
+  onSpeechEnd: func
+});
+bricks.vad.start();
+```
+
+---
+
+### `bricks.disable_vad()`
+
+停止当前运行的 VAD 实例，并释放相关资源。
+
+#### 行为说明
+- 调用 `stop()` 方法停止麦克风监听和模型推理
+- 将 `bricks.vad` 设置为 `null`，便于垃圾回收
+
+#### 示例
+
+```javascript
+// 停止语音检测
+bricks.disable_vad();
+```
+
+---
+
+## 音频数据格式
+
+- **采样率**：16000 Hz
+- **位深**：32-bit float
+- **声道**：单声道（Mono）
+- **数据类型**：`Float32Array`
+- **应用场景**：适用于大多数现代语音识别（ASR）模型输入要求
+
+---
+
+## 使用示例
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>VAD Demo</title>
+</head>
+<body>
+  <button onclick="startVAD()">开始语音检测</button>
+  <button onclick="stopVAD()">停止语音检测</button>
+
+  <script src="https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/ort.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@ricky0123/vad-web@0.0.7/dist/bundle.min.js"></script>
+  <script>
+    var bricks = window.bricks || {};
+    
+    bricks.enable_vad = async function(func){
+      bricks.vad = await vad.MicVAD.new({
+        onSpeechEnd: func
+      });
+      bricks.vad.start();
+    };
+
+    bricks.disable_vad = async function(){
+      if (bricks.vad) {
+        bricks.vad.stop();
+        bricks.vad = null;
+      }
+    };
+
+    function startVAD() {
+      bricks.enable_vad((audio) => {
+        console.log("捕获到语音片段，样本数:", audio.length);
+        // 此处可上传至 ASR 服务或进行本地处理
+      });
+    }
+
+    function stopVAD() {
+      bricks.disable_vad();
+    }
+  </script>
+</body>
+</html>
+```
+
+---
+
+## 注意事项
+
+1. **浏览器权限**：首次运行时需请求麦克风权限，请确保页面在 HTTPS 环境下运行或本地调试（localhost）。
+2. **性能优化**：`vad-web` 使用 WASM 和 ONNX 模型进行推理，首次加载可能需要几秒预热时间。
+3. **内存管理**：务必在不需要时调用 `disable_vad()` 以释放麦克风资源，避免持续占用。
+4. **版本锁定**：当前固定使用 `@ricky0123/vad-web@0.0.7`，建议生产环境保持版本稳定。
+
+---
+
+## 参考链接
+
+- [vad-web GitHub 仓库](https://github.com/ricky0123/vad-web)
+- [ONNX Runtime Web](https://onnxruntime.ai/docs/tutorials/web/intro.html)
+- [Web Audio API 文档](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
+
+---
+
+## 版本信息
+
+- **vad-web 版本**：`0.0.7`
+- **兼容性**：支持现代主流浏览器（Chrome、Edge、Firefox、Safari）
+
+--- 
+
+📌 **提示**：此模块适合嵌入到低代码平台、语音助手、实时对话系统中，作为前端语音触发机制的核心组件。
\ No newline at end of file
diff --git a/aidocs/page_data_loader.md b/aidocs/page_data_loader.md
new file mode 100644
index 0000000..d0c307e
--- /dev/null
+++ b/aidocs/page_data_loader.md
@@ -0,0 +1,317 @@
+# `bricks.PageDataLoader` 技术文档
+
+`PageDataLoader` 是一个用于分页加载数据的 JavaScript 类，支持缓存控制、参数合并、前后翻页等功能。它适用于需要从后端 API 按页获取大量数据的场景，并通过缓存机制优化性能。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [依赖说明](#依赖说明)
+- [构造函数与配置选项](#构造函数与配置选项)
+- [实例方法](#实例方法)
+  - [`loadData([params])`](#loaddataparams)
+  - [`loadNextPage()`](#loadnextpage)
+  - [`loadPreviousPage()`](#loadpreviouspage)
+  - [`loadPage(page)`](#loadpagepage)
+  - [`is_max_page(p)`](#is_max_pagep)
+- [返回数据结构](#返回数据结构)
+- [使用示例](#使用示例)
+- [缓存策略](#缓存策略)
+- [注意事项](#注意事项)
+
+---
+
+## 概述
+
+`bricks.PageDataLoader` 提供了一个简洁的接口来管理分页数据的加载和缓存。其主要特性包括：
+
+- 支持自定义请求 URL、分页大小、HTTP 方法等。
+- 自动计算总页数。
+- 内置页面缓存机制（可配置最大缓存页数）。
+- 支持跳转到指定页、下一页、上一页。
+- 可扩展的基础参数与动态参数合并。
+
+---
+
+## 依赖说明
+
+该类依赖以下全局对象或模块：
+
+| 依赖 | 说明 |
+|------|------|
+| `window.bricks` | 全局命名空间对象，提供工具函数 |
+| `bricks.extend(obj1, obj2)` | 对象浅拷贝并合并属性（类似 jQuery 的 `$.extend`） |
+| `bricks.HttpJson()` | 发起 HTTP 请求的封装类，支持 `.httpcall(url, options)` 方法 |
+| `bricks.debug(...)` | 调试日志输出函数 |
+
+> ⚠️ 确保这些依赖在运行环境中已正确加载。
+
+---
+
+## 构造函数与配置选项
+
+```js
+var loader = new bricks.PageDataLoader(options);
+```
+
+### 参数：`options` (Object)
+
+| 属性名        | 类型     | 必填 | 默认值 | 说明 |
+|---------------|----------|------|--------|------|
+| `url`         | String   | ✅   | -      | 数据接口地址 |
+| `pagerows`    | Number   | ❌   | 80     | 每页显示的数据条数 |
+| `cache_pages` | Number   | ❌   | 5      | 最多缓存多少个页面（超出则移除最远页） |
+| `method`      | String   | ❌   | `'GET'` | HTTP 请求方法（如 `'POST'`） |
+| `params`      | Object   | ❌   | `{}`   | 基础请求参数（每次请求都会携带） |
+
+### 示例
+
+```js
+var p = new bricks.PageDataLoader({
+  url: '/api/data',
+  pagerows: 50,
+  cache_pages: 3,
+  method: 'GET',
+  params: {
+    category: 'news'
+  }
+});
+```
+
+---
+
+## 实例方法
+
+### `loadData([params])`
+
+初始化并加载第一页数据。
+
+#### 参数
+
+- `params` (Object, 可选)：本次请求附加的参数，会与 `base_params` 合并。
+
+#### 返回值
+
+- Promise：解析为第一页的响应数据（包含分页信息）。
+
+#### 行为说明
+
+- 清空当前所有缓存页。
+- 合并基础参数与传入参数。
+- 调用 `loadPage(1)` 加载第一页。
+
+#### 示例
+
+```js
+p.loadData({ search: 'keyword' }).then(data => {
+  console.log(data);
+});
+```
+
+---
+
+### `loadNextPage()`
+
+加载下一页数据（即当前已加载页码的最大值 + 1）。
+
+#### 返回值
+
+- Promise：若存在下一页，则返回下一页数据；否则返回 `undefined`。
+
+#### 条件判断
+
+- 仅当目标页未加载且小于等于 `lastPage` 时才发起请求。
+
+#### 示例
+
+```js
+p.loadNextPage().then(data => {
+  if (data) {
+    render(data.rows); // 渲染新页数据
+  }
+});
+```
+
+---
+
+### `loadPreviousPage()`
+
+加载上一页数据（即当前已加载页码的最小值 - 1）。
+
+#### 返回值
+
+- Promise：若存在上一页（页码 > 0），则返回对应数据；否则返回 `undefined`。
+
+#### 示例
+
+```js
+p.loadPreviousPage().then(data => {
+  if (data) {
+    prependToView(data.rows); // 将数据插入视图开头
+  }
+});
+```
+
+---
+
+### `loadPage(page)`
+
+加载指定页码的数据（核心方法）。
+
+#### 参数
+
+- `page` (Number)：要加载的页码（从 1 开始）。
+
+#### 返回值
+
+- Promise：返回该页的完整响应数据。
+
+#### 行为说明
+
+1. 若该页已加载（存在于 `this.pages` 中），不重复请求。
+2. 使用 `bricks.HttpJson().httpcall()` 发起请求：
+   ```js
+   {
+     page: page,
+     rows: this.rows
+   }
+   ```
+3. 自动更新 `lastPage`（根据 `total / rows` 计算）。
+4. 将当前页加入 `pages` 缓存数组。
+5. 若缓存超过 `cache_pages` 数量，则删除“最远”的一页（相对于当前页是首或尾）。
+6. 在返回数据中添加元字段（如 `add_page`, `delete_page`, `pos_rate`）。
+
+#### 扩展字段说明
+
+| 字段名       | 类型   | 说明 |
+|--------------|--------|------|
+| `add_page`   | Number | 当前新增的页码 |
+| `delete_page`| Number | 因缓存溢出被删除的页码（如有） |
+| `pos_rate`   | Number | 当前位置占比（用于 UI 定位提示） |
+| `last_page`  | Number | 总页数（由后端 `total` 推导） |
+
+---
+
+### `is_max_page(p)`
+
+判断某页是否为当前已知的最大页码。
+
+#### 参数
+
+- `p` (Number)：待检测的页码。
+
+#### 返回值
+
+- Boolean：如果是当前缓存中的最大页码，返回 `true`。
+
+#### 示例
+
+```js
+if (p.is_max_page(5)) {
+  console.log("这是当前最大的页码");
+}
+```
+
+---
+
+## 返回数据结构
+
+假设后端返回格式如下：
+
+```json
+{
+  "total": 230,
+  "rows": [...]
+}
+```
+
+`PageDataLoader` 会在基础上增加以下字段：
+
+```json
+{
+  "total": 230,
+  "rows": [...],
+  "last_page": 3,
+  "add_page": 1,
+  "delete_page": 3,
+  "pos_rate": 0.5
+}
+```
+
+| 字段         | 说明 |
+|--------------|------|
+| `last_page`  | 根据 `Math.ceil(total / rows)` 得出的总页数 |
+| `add_page`   | 本次成功加载的页码 |
+| `delete_page`| 如果触发了缓存清理，表示被清除的页码 |
+| `pos_rate`   | 当前页在已有页中的相对位置（0 ~ 1），便于 UI 定位 |
+
+---
+
+## 使用示例
+
+```js
+// 初始化加载器
+var loader = new bricks.PageDataLoader({
+  url: '/api/list',
+  params: { type: 'article' },
+  pagerows: 20,
+  cache_pages: 4,
+  method: 'GET'
+});
+
+// 加载第一页
+loader.loadData().then(data => {
+  displayData(data.rows);
+  console.log(`共 ${data.last_page} 页`);
+});
+
+// 下一页
+document.getElementById('next').onclick = () => {
+  loader.loadNextPage().then(data => {
+    if (data) appendData(data.rows);
+  });
+};
+
+// 上一页
+document.getElementById('prev').onclick = () => {
+  loader.loadPreviousPage().then(data => {
+    if (data) prependData(data.rows);
+  });
+};
+```
+
+---
+
+## 缓存策略
+
+- 所有已成功加载的页码记录在 `this.pages` 数组中。
+- 当 `pages.length > cache_pages` 时，自动删除“最远”的一页：
+  - 若当前加载的是最后一页 → 删除最早页（最小页码）
+  - 若当前加载的是较早页 → 删除最后页（最大页码）
+
+> 此策略有助于保持用户浏览路径附近的页数据在内存中。
+
+---
+
+## 注意事项
+
+1. **异步调用**：所有 `loadXxx` 方法均为 `async`，需使用 `await` 或 `.then()` 处理结果。
+2. **页码从 1 开始**：符合常规分页习惯。
+3. **无重复加载**：已加载的页不会再次请求，需手动调用 `loadData()` 重置。
+4. **错误处理**：请求失败时会通过 `bricks.debug()` 输出调试信息，但不会抛出异常。
+5. **total 必须存在**：后端响应必须包含 `total` 字段，否则无法计算 `lastPage`。
+
+---
+
+## 版本信息
+
+- 模块名称：`bricks.PageDataLoader`
+- 创建时间：未知
+- 维护者：`window.bricks` 团队
+
+> 如需定制行为，建议继承此类或扩展原型方法。
+
+--- 
+
+✅ **推荐用途**：表格分页、无限滚动、左右滑动浏览历史记录等场景。
\ No newline at end of file
diff --git a/aidocs/paging.md b/aidocs/paging.md
new file mode 100644
index 0000000..5ab3485
--- /dev/null
+++ b/aidocs/paging.md
@@ -0,0 +1,272 @@
+# `bricks.BufferedDataLoader` 技术文档
+
+> 一个用于分页加载数据并支持缓冲机制的前端数据加载器。
+
+---
+
+## 概述
+
+`bricks.BufferedDataLoader` 是一个 JavaScript 类，旨在为需要高效处理大量分页数据的 UI 组件（如表格、列表等）提供**带缓冲的数据加载能力**。它通过限制内存中缓存的页面数量来优化性能，并支持向前/向后翻页操作。
+
+该类适用于与支持分页接口的后端服务配合使用，典型场景包括大数据量表格滚动加载、虚拟滚动列表等。
+
+---
+
+## 命名空间
+
+```js
+bricks.BufferedDataLoader
+```
+
+依赖于全局对象 `window.bricks`，若不存在则自动创建。
+
+---
+
+## 构造函数
+
+### `new bricks.BufferedDataLoader(widget, options)`
+
+#### 参数
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `widget` | Object | ✅ | 数据展示组件实例，必须实现 `.clear_data()`, `.add_rows(rows, direction)`, `.del_old_rows(count, direction)` 方法。 |
+| `opts` | Object | ✅ | 配置选项对象，详见下表。 |
+
+#### `opts` 配置项
+
+| 属性 | 类型 | 可选 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `url` | String | ❌ | - | 请求数据的 API 地址。 |
+| `method` | String | ✅ | `'GET'` | HTTP 请求方法，如 `'GET'` 或 `'POST'`。 |
+| `params` | Object | ✅ | `{}` | 固定请求参数（例如过滤条件、排序字段等）。 |
+| `buffer_pages` | Number | ✅ | `5` | 最大缓存页数，超出时将移除最旧或最新的一页以释放内存。 |
+| `pagerows` | Number | ✅ | `60` | 每页返回的数据行数。 |
+
+---
+
+## 实例属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `cur_page` | Number | 当前正在加载/显示的页码（从 1 开始）。 |
+| `total_records` | Number | 总记录数（由服务器返回填充）。 |
+| `total_page` | Number | 总页数（根据 `total_records / pagerows` 计算得出）。 |
+| `buffer` | Object | （预留扩展）当前用于存储已加载页面数据的缓存对象（本版本未实际使用）。 |
+| `buffered_pages` | Number | 当前缓冲中的页面数量（影响是否触发旧数据清理）。 |
+| `loading` | Boolean | 标志位，表示是否正在进行网络请求。 |
+| `direction` | String | 上下方向标识：`'up'` 表示上一页，`'down'` 表示下一页，用于通知 widget 渲染策略。 |
+| `cur_params` | Object | 合并后的当前请求参数（包含固定参数和动态传参）。 |
+
+---
+
+## 方法
+
+### `initial()`
+重置加载器状态，通常在初始化或重新加载前调用。
+
+#### 功能：
+- 重置当前页为 `-1`
+- 清空缓冲计数
+- 重置总记录数
+- 清空当前参数副本
+
+---
+
+### `async loadData(params)`
+初始化并加载第一页数据，清空现有数据。
+
+#### 参数：
+- `params` *(Object, 可选)*: 动态附加的请求参数（会与 `opts.params` 合并）
+
+#### 返回值：
+- `Promise<Object>`: 解析为服务器返回的数据结构，包含：
+  ```js
+  {
+    total: 1000,
+    page: 1,
+    total_page: 17,
+    rows: [...]
+  }
+  ```
+
+#### 流程：
+1. 调用 `initial()` 重置状态
+2. 清空 widget 显示数据
+3. 合并默认参数与传入参数
+4. 设置每页行数 (`rows`) 和初始页码 (`page=1`)
+5. 调用 `loadPage()` 加载第一页
+
+#### 示例：
+```js
+const loader = new bricks.BufferedDataLoader(myWidget, {
+  url: '/api/data',
+  params: { category: 'A' },
+  pagerows: 50
+});
+
+await loader.loadData({ search: 'keyword' }); // 发送 {category:'A', search:'keyword', rows:50, page:1}
+```
+
+---
+
+### `async loadPage(page)`
+加载指定页码的数据（内部方法，也可手动调用）。
+
+#### 参数：
+- `page` *(Number, 可选)*: 指定要加载的页码，默认为当前 `this.cur_page + 1`（如果未设置）
+
+> ⚠️ 注意：此方法内部管理 `cur_page`，外部应优先使用 `nextPage()` / `previousPage()`。
+
+#### 行为逻辑：
+1. 若正在加载，则直接返回（防重复提交）
+2. 若缓冲页数达到上限（`buffer_pages`），则调用 `widget.del_old_rows()` 删除旧行
+3. 构造完整请求参数（含 `page`, `rows` 等）
+4. 使用 `bricks.HttpJson` 发起异步请求
+5. 更新总记录数和总页数
+6. 调用 `widget.add_rows()` 添加新数据
+7. 增加缓冲页计数，释放加载锁
+
+#### 返回值：
+- `Promise<Object>`: 服务器响应数据
+
+---
+
+### `async nextPage()`
+加载下一页数据。
+
+#### 条件判断：
+- 如果已在最后一页或正在加载，则不执行任何操作。
+
+#### 行为：
+- 设置 `direction = 'down'`
+- `cur_page += 1`
+- 调用 `loadPage()`
+
+#### 示例：
+```js
+await loader.nextPage(); // 加载第 2 页
+```
+
+---
+
+### `async previousPage()`
+加载上一页数据。
+
+#### 条件判断：
+- 如果已是第一页或正在加载，则不执行。
+
+#### 行为：
+- 设置 `direction = 'up'`
+- `cur_page -= 1`
+- 调用 `loadPage()`
+
+#### 示例：
+```js
+await loader.previousPage(); // 回退到前一页
+```
+
+---
+
+## widget 接口要求
+
+`BufferedDataLoader` 依赖传入的 `widget` 实现以下三个方法：
+
+| 方法 | 签名 | 用途 |
+|------|------|------|
+| `.clear_data()` | `function(): void` | 清空当前所有数据显示 |
+| `.add_rows(rows, direction)` | `function(Array, String): void` | 添加一批数据行，`direction` 为 `'up'` 或 `'down'`，可用于决定插入位置 |
+| `.del_old_rows(count, direction)` | `function(Number, String): void` | 删除旧数据行（例如顶部或底部若干行），用于维持缓冲大小 |
+
+> 💡 提示：这些方法可结合虚拟滚动、DOM 复用等技术实现高性能渲染。
+
+---
+
+## 使用示例
+
+```js
+// 定义 widget 对象（模拟组件）
+const myWidget = {
+  data: [],
+  clear_data() {
+    this.data = [];
+    console.log("数据已清空");
+  },
+  add_rows(rows, direction) {
+    if (direction === 'up') {
+      this.data.unshift(...rows);
+    } else {
+      this.data.push(...rows);
+    }
+    console.log(`添加了 ${rows.length} 行数据，方向: ${direction}`);
+  },
+  del_old_rows(count, direction) {
+    if (direction === 'up') {
+      this.data.splice(-count); // 删除末尾
+    } else {
+      this.data.splice(0, count); // 删除开头
+    }
+    console.log(`删除了 ${count} 行旧数据`);
+  }
+};
+
+// 创建 BufferedDataLoader 实例
+const loader = new bricks.BufferedDataLoader(myWidget, {
+  url: '/api/list',
+  method: 'POST',
+  params: { type: 'report' },
+  buffer_pages: 3,
+  pagerows: 20
+});
+
+// 初始加载第一页
+await loader.loadData({ keyword: 'test' });
+
+// 下一页
+await loader.nextPage();
+
+// 上一页
+await loader.previousPage();
+```
+
+---
+
+## 注意事项
+
+1. **线程安全**：通过 `this.loading` 实现简单的并发控制，防止重复请求。
+2. **内存控制**：通过 `buffer_pages` 控制最大缓存页数，避免内存溢出。
+3. **方向感知**：`direction` 字段帮助 widget 区分上下滑动行为，便于优化 UI 渲染。
+4. **总页数计算修正**：
+   ```js
+   if (d.total_page * this.pagerows < this.total_record) {
+     d.total_page += 1;
+   }
+   ```
+   此处逻辑存在潜在错误（应使用向上取整），建议改为：
+   ```js
+   d.total_page = Math.ceil(d.total / this.pagerows);
+   ```
+
+---
+
+## 改进建议
+
+| 问题 | 建议修复 |
+|------|---------|
+| `total_page` 计算错误 | 改为 `Math.ceil(total / pagerows)` |
+| `buffer` 成员未实际使用 | 应实现真正的页面数据缓存以支持快速回退 |
+| 缺少错误处理 | 在 `httpcall` 外包裹 `try-catch` 并抛出异常 |
+| 不支持取消请求 | 可引入 `AbortController` 实现请求中断 |
+
+---
+
+## 版本信息
+
+- 所属库：`bricks.js`
+- 类名：`BufferedDataLoader`
+- 创建时间：未知
+- 作者：未知
+
+--- 
+
+📖 **文档生成于：2025年4月5日**
\ No newline at end of file
diff --git a/aidocs/period.md b/aidocs/period.md
new file mode 100644
index 0000000..5f537a3
--- /dev/null
+++ b/aidocs/period.md
@@ -0,0 +1,322 @@
+# `bricks` 日期工具与组件库技术文档
+
+---
+
+## 概述
+
+`bricks` 是一个轻量级的 JavaScript 工具和 UI 组件库，提供常用的日期处理函数以及可交互的日期周期控件。本文档详细说明其核心功能模块：
+
+- 日期字符串与 `Date` 对象之间的转换
+- 日期增减操作（天、月、年）
+- `PeriodDays` 可点击切换周期的 UI 控件
+
+该库设计用于前端项目中快速构建时间范围选择器等交互式组件。
+
+---
+
+## 全局命名空间
+
+```js
+var bricks = window.bricks || {};
+```
+
+> 所有功能均挂载在全局 `bricks` 命名空间下，避免污染全局作用域。
+
+---
+
+## 1. `bricks.str2date(sdate)`
+
+将格式为 `"YYYY-MM-DD"` 的字符串转换为 `Date` 对象。
+
+### 参数
+
+| 参数名   | 类型   | 描述                   |
+|----------|--------|------------------------|
+| `sdate`  | string | 格式为 `"YYYY-MM-DD"` 的日期字符串 |
+
+### 返回值
+
+- `{Date}`：对应的 `Date` 对象（注意：月份从 0 开始）
+
+### 示例
+
+```js
+bricks.str2date("2025-04-05"); // 返回 Date 对象，表示 2025年4月5日
+```
+
+### 注意事项
+
+- 输入字符串必须符合 `YYYY-MM-DD` 格式。
+- `new Date(year, month - 1, day)` 中月份需减 1，因 JS 的 `Date` 对象月份从 0 起始。
+
+---
+
+## 2. `bricks.date2str(date)`
+
+将 `Date` 对象格式化为 `"YYYY-MM-DD"` 字符串。
+
+### 参数
+
+| 参数名   | 类型   | 描述               |
+|----------|--------|--------------------|
+| `date`   | Date   | 要格式化的日期对象 |
+
+### 返回值
+
+- `{string}`：格式化后的 `"YYYY-MM-DD"` 字符串，不足两位自动补零。
+
+### 示例
+
+```js
+const d = new Date(2025, 3, 5); // 2025-04-05
+bricks.date2str(d); // "2025-04-05"
+```
+
+---
+
+## 3. `bricks.addMonths(dateObj, months)`
+
+在指定日期上增加若干个月。
+
+### 参数
+
+| 参数名     | 类型   | 描述                     |
+|------------|--------|--------------------------|
+| `dateObj`  | Date   | 原始日期对象             |
+| `months`   | number | 要增加的月数（可为负）   |
+
+### 返回值
+
+- `{Date}`：新的 `Date` 对象，原对象不被修改
+
+### 示例
+
+```js
+const d = new Date(2025, 0, 15); // 2025-01-15
+bricks.addMonths(d, 3); // 2025-04-15
+bricks.addMonths(d, -1); // 2024-12-15
+```
+
+---
+
+## 4. `bricks.addYears(dateObj, years)`
+
+在指定日期上增加若干年。
+
+### 参数
+
+| 参数名    | 类型   | 描述                     |
+|-----------|--------|--------------------------|
+| `dateObj` | Date   | 原始日期对象             |
+| `years`   | number | 要增加的年数（可为负）   |
+
+### 返回值
+
+- `{Date}`：新的 `Date` 对象
+
+### ⚠️ 注意
+
+使用了 `setYear()` 方法，但请注意：
+- `setYear()` 在现代 JS 中已被弃用，推荐使用 `setFullYear()` 替代。
+- 当前实现可能存在问题：`getYear()` 返回的是相对于 1900 的偏移量，因此 `+ years` 实际上是错误逻辑！
+
+### ✅ 修正建议
+
+```js
+bricks.addYears = function(dateObj, years){
+    const newDate = new Date(dateObj);
+    newDate.setFullYear(newDate.getFullYear() + years);
+    return newDate;
+}
+```
+
+> 建议尽快替换以确保跨世纪正确性（如 2099 → 2100 年等问题）。
+
+---
+
+## 5. `bricks.addDays(dateObj, days)`
+
+在指定日期上增加若干天。
+
+### 参数
+
+| 参数名   | 类型   | 描述                     |
+|----------|--------|--------------------------|
+| `dateObj`| Date   | 原始日期对象             |
+| `days`   | number | 要增加的天数（可为负）   |
+
+### 返回值
+
+- `{Date}`：新的 `Date` 对象
+
+### 示例
+
+```js
+const d = new Date(2025, 0, 1);
+bricks.addDays(d, 10);  // 2025-01-11
+bricks.addDays(d, -1);  // 2024-12-31
+```
+
+---
+
+## 6. `bricks.PeriodDays` —— 周期日期选择控件
+
+一个继承自 `bricks.HBox` 的 UI 组件，允许用户通过点击前后文本切换时间区间。
+
+### 继承关系
+
+```js
+class PeriodDays extends bricks.HBox
+```
+
+### 配置选项 (`opts`)
+
+| 属性名       | 类型     | 默认值      | 描述 |
+|--------------|----------|-------------|------|
+| `start_date` | string   | 必填        | 起始日期 `"YYYY-MM-DD"` |
+| `end_date`   | string   | 必填        | 结束日期 `"YYYY-MM-DD"` |
+| `step_type`  | string   | `'days'`    | 步进类型：`'days'`, `'months'`, `'years'` |
+| `step_cnt`   | number   | `1`         | 每次步进的数量 |
+| `title`      | string   | `undefined` | 显示标题（支持国际化） |
+| `splitter`   | string   | `' 至 '`    | 分隔符文本，显示在起止日期之间 |
+
+### 支持事件
+
+- **`changed`**：当日期范围发生变化时触发，携带新范围数据。
+
+#### 事件参数结构
+
+```json
+{
+  "start_date": "YYYY-MM-DD",
+  "end_date": "YYYY-MM-DD"
+}
+```
+
+### 成员方法
+
+#### `date_add(strdate, step_cnt, step_type)`
+
+内部方法：对字符串日期执行加法运算并返回新字符串。
+
+##### 参数
+
+| 参数名       | 类型     | 描述 |
+|--------------|----------|------|
+| `strdate`    | string   | 输入日期字符串 |
+| `step_cnt`   | number   | 步进步数 |
+| `step_type`  | string   | `'days'`, `'months'`, `'years'` |
+
+##### 返回值
+
+- `{string}`：结果日期字符串（格式 `"YYYY-MM-DD"`）
+
+##### 示例
+
+```js
+this.date_add("2025-01-01", 1, "months"); // "2025-02-01"
+```
+
+---
+
+#### `step_back()`
+
+点击起始日期时触发，整体周期向前移动（减去步长）。
+
+- 更新 `start_date` 和 `end_date`
+- 刷新界面显示
+- 触发 `changed` 事件
+
+---
+
+#### `step_forward()`
+
+点击结束日期时触发，整体周期向后移动（加上步长）。
+
+- 同上，方向相反
+
+---
+
+### 用户交互设计
+
+| 元素           | 行为                         |
+|----------------|------------------------------|
+| 起始日期文本   | 点击 → 周期整体前移          |
+| 结束日期文本   | 点击 → 周期整体后移          |
+
+> 文本添加了 `clickable` CSS 类，并绑定点击事件。
+
+---
+
+### 使用示例
+
+```js
+const period = new bricks.PeriodDays({
+    start_date: "2025-01-01",
+    end_date: "2025-01-31",
+    step_type: "months",
+    step_cnt: 1,
+    title: "统计周期",
+    splitter: " 至 "
+});
+
+// 监听变化
+period.bind('changed', function(e){
+    console.log("新周期:", e.start_date, "到", e.end_date);
+});
+```
+
+渲染效果类似：
+
+```
+统计周期  2025-01-01 至 2025-01-31
+```
+
+点击 “2025-01-01” → 变为 “2024-12-01 至 2024-12-31”  
+点击 “2025-01-31” → 变为 “2025-02-01 至 2025-02-28”
+
+---
+
+## 注册组件
+
+```js
+bricks.Factory.register('PeriodDays', bricks.PeriodDays);
+```
+
+> 使得可通过工厂模式动态创建此组件。
+
+---
+
+## 总结
+
+| 功能                 | 是否推荐使用 | 备注 |
+|----------------------|--------------|------|
+| `str2date` / `date2str` | ✅ 推荐       | 安全可靠 |
+| `addDays` / `addMonths` | ✅ 推荐       | 正确封装 |
+| `addYears`            | ⚠️ 需修复     | 应改用 `setFullYear` |
+| `PeriodDays`          | ✅ 推荐       | 交互清晰，适合报表周期切换 |
+
+---
+
+## 附录：已知问题与改进建议
+
+1. ❗ `addYears` 使用 `getYear/setYear` 存在兼容性和逻辑错误，应改为：
+
+```js
+bricks.addYears = function(dateObj, years) {
+    const newDate = new Date(dateObj);
+    newDate.setFullYear(newDate.getFullYear() + years);
+    return newDate;
+};
+```
+
+2. ✅ 所有日期操作均创建副本，保护原始对象，良好实践。
+
+3. 🔹 `PeriodDays` 未做边界校验（如非法日期），建议增加输入验证。
+
+4. 🔹 支持更多 `step_type` 如 `'weeks'` 可扩展性更强。
+
+--- 
+
+> 文档版本：v1.0  
+> 最后更新：2025年4月5日
\ No newline at end of file
diff --git a/aidocs/pie.md b/aidocs/pie.md
new file mode 100644
index 0000000..997d10e
--- /dev/null
+++ b/aidocs/pie.md
@@ -0,0 +1,257 @@
+# `bricks.ChartPie` 技术文档
+
+## 概述
+
+`bricks.ChartPie` 是基于 `bricks.EchartsExt` 扩展的类，用于创建可配置的饼图组件。它利用 ECharts 作为底层图表引擎，支持通过数据接口动态加载数据，并自动生成饼图及其图例。
+
+该组件适用于需要展示分类占比数据的场景，如统计分析、仪表盘等。
+
+---
+
+## 继承关系
+
+```js
+class ChartPie extends bricks.EchartsExt
+```
+
+继承自 `bricks.EchartsExt`，具备基础的图表初始化、数据获取和事件处理能力。
+
+---
+
+## 构造函数
+
+### `constructor(opts)`
+
+#### 参数
+
+| 参数名 | 类型   | 说明 |
+|--------|--------|------|
+| `opts` | Object | 配置选项对象，传递给父类及内部逻辑使用 |
+
+#### 示例
+
+```js
+var pieChart = new bricks.ChartPie({
+    nameField: 'category',
+    valueFields: ['sales'],
+    data_url: '/api/pie-data',
+    pie_options: {
+        type: 'pie',
+        radius: '70%'
+    },
+    legend: {
+        show: true,
+        orient: 'vertical'
+    }
+});
+```
+
+> ⚠️ 注意：构造函数中调用了 `super(opts)`，因此所有父类支持的配置项也适用。
+
+---
+
+## 配置选项（Options）
+
+| 属性名         | 类型     | 必填 | 默认值 | 说明 |
+|----------------|----------|------|--------|------|
+| `title`        | String   | 否   | -      | 图表标题 |
+| `description`  | String   | 否   | -      | 图表描述信息（可用于辅助提示） |
+| `legend`       | Object   | 否   | `{}`   | 图例配置项，将直接传入 ECharts 的 `legend` 配置 |
+| `pie_options`  | Object   | 是   | -      | 饼图系列的核心配置，如 `type`, `radius`, `center` 等 |
+| `data_url`     | String   | 否   | -      | 数据接口 URL，若提供则自动异步加载数据 |
+| `nameField`    | String   | 是   | -      | 指定哪一字段作为饼图扇区的名称（即类别） |
+| `valueFields`  | Array    | 是   | -      | 数组形式指定值字段（目前仅取第一个字段用于数值） |
+| `data_params`  | Object   | 否   | -      | 请求 `data_url` 时携带的额外参数 |
+| `data`         | Array    | 否   | `[]`   | 直接传入的静态数据数组 |
+
+---
+
+## 核心方法
+
+### `setup_options(data)`
+
+根据传入的数据生成符合 ECharts 要求的图表配置项。
+
+#### 参数
+
+| 参数名 | 类型  | 说明 |
+|-------|-------|------|
+| `data` | Array | 原始数据数组，通常来自 API 或静态赋值 |
+
+#### 返回值
+
+返回一个符合 ECharts schema 的配置对象，结构如下：
+
+```js
+{
+    legend: { ... },           // 图例配置
+    tooltip: {
+        trigger: 'item'        // 鼠标悬停显示单项详情
+    },
+    series: [
+        { /* 处理后的饼图系列配置 */ }
+    ]
+}
+```
+
+#### 内部逻辑说明
+
+1. **数据映射**：
+   - 使用 `this.nameField` 映射为每个扇区的 `name`
+   - 使用 `this.valueFields[0]` 映射为 `value`
+   - 构建新的数据格式：`{ name: '类别A', value: 100 }`
+
+2. **合并饼图配置**：
+   - 使用 `bricks.extend({}, this.pie_options)` 深拷贝避免污染原始配置
+   - 将处理后的数据注入到 `series[0].data`
+
+3. **图例处理**：
+   - 若设置了 `legend`，则保留其配置
+   - 注释代码表明原计划支持多字段图例，当前未启用
+
+#### 示例输出
+
+假设输入数据为：
+
+```js
+[
+    { category: "手机", sales: 60 },
+    { category: "平板", sales: 40 }
+]
+```
+
+且配置为：
+
+```js
+{
+    nameField: 'category',
+    valueFields: ['sales'],
+    pie_options: { type: 'pie', radius: '80%' }
+}
+```
+
+则 `setup_options` 输出为：
+
+```js
+{
+    legend: {},
+    tooltip: { trigger: 'item' },
+    series: [{
+        type: 'pie',
+        radius: '80%',
+        data: [
+            { name: '手机', value: 60 },
+            { name: '平板', value: 40 }
+        ]
+    }]
+}
+```
+
+---
+
+## 支持的事件
+
+### `element_click`
+
+当用户点击饼图中的某个扇区时触发。
+
+#### 回调参数
+
+ECharts 提供的标准事件参数对象，包含：
+
+- `name`: 扇区名称
+- `value`: 对应数值
+- `data`: 原始数据项
+- `seriesName`: 系列名称（如有）
+
+#### 使用方式
+
+```js
+pieChart.on('element_click', function(e) {
+    console.log('Clicked:', e.name, e.value);
+});
+```
+
+---
+
+## 注册与使用
+
+### 注册组件
+
+```js
+bricks.Factory.register('ChartPie', bricks.ChartPie);
+```
+
+通过工厂模式注册，后续可通过字符串标识符创建实例：
+
+```js
+var chart = bricks.Factory.create('ChartPie', options);
+```
+
+---
+
+## 完整示例
+
+```js
+// 初始化饼图
+var myPie = new bricks.ChartPie({
+    nameField: 'product',
+    valueFields: ['revenue'],
+    data_url: '/report/sales-by-product',
+    data_params: { year: 2024 },
+    pie_options: {
+        type: 'pie',
+        radius: ['50%', '70%'],
+        label: {
+            show: true,
+            formatter: '{b}: {d}%'
+        }
+    },
+    legend: {
+        show: true,
+        orient: 'horizontal',
+        bottom: '0%'
+    },
+    title: '2024 年产品收入分布'
+});
+
+// 渲染到 DOM 元素
+myPie.renderTo('#chart-container');
+
+// 绑定点击事件
+myPie.on('element_click', function(e) {
+    alert(`您点击了：${e.name}`);
+});
+```
+
+---
+
+## 注意事项
+
+1. **`valueFields` 仅支持单个值字段**  
+   当前实现只取数组的第一个字段作为数值来源，不支持多维度饼图。
+
+2. **数据格式要求**  
+   从接口或手动传入的数据必须是对象数组，且包含 `nameField` 和 `valueFields[0]` 字段。
+
+3. **依赖 `bricks.extend` 工具函数**  
+   用于安全拷贝 `pie_options`，确保不影响原始配置。
+
+4. **需提前引入 ECharts**  
+   本组件依赖全局 ECharts 库，请确保页面已正确加载。
+
+---
+
+## 版本信息
+
+- 创建时间：未知
+- 最后更新：根据代码注释推断近期维护中
+- 所属框架：`bricks.js` 可视化组件库
+
+--- 
+
+✅ **建议扩展方向**：
+- 支持多层环形图（嵌套饼图）
+- 添加动画配置开关
+- 支持主题颜色自定义
+- 增加空数据状态提示
\ No newline at end of file
diff --git a/aidocs/popup.md b/aidocs/popup.md
new file mode 100644
index 0000000..1ab9b56
--- /dev/null
+++ b/aidocs/popup.md
@@ -0,0 +1,502 @@
+# Bricks UI Framework - Popup 组件技术文档
+
+---
+
+## 概述
+
+`bricks.Popup` 是基于 `bricks.VBox` 的弹窗组件，用于创建可浮动、可移动、可调整大小的模态或非模态对话框。它支持自动打开/关闭、点击外部区域自动关闭、内容动态加载等功能。
+
+此外，框架还提供了两个扩展类：
+- `bricks.PopupWindow`：带标题栏和控制按钮（最小化、全屏、关闭）的窗口式弹窗。
+- `bricks.WindowsPanel`：用于管理多个最小化的窗口列表面板。
+
+该组件适用于构建现代化 Web 应用中的对话框、提示框、应用窗口等交互界面。
+
+---
+
+## 全局命名空间初始化
+
+```js
+var bricks = window.bricks || {};
+```
+
+确保 `bricks` 命名空间存在，避免覆盖已有对象。
+
+---
+
+## 默认配置方法
+
+### `bricks.get_popup_default_options()`
+
+返回一个包含默认选项的对象，供 `Popup` 使用。
+
+#### 返回值
+```js
+{
+  timeout: 0,
+  archor: 'cc',
+  auto_open: true,
+  auto_dismiss: true,
+  auto_destroy: true,
+  movable: true,
+  resizable: false,
+  modal: true
+}
+```
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `timeout` | Number | 自动关闭延迟时间（秒），设为 0 表示不自动关闭 |
+| `archor` | String | 定位锚点，取值见下表 |
+| `auto_open` | Boolean | 是否在实例化后自动打开弹窗 |
+| `auto_dismiss` | Boolean | 是否允许点击外部区域关闭弹窗 |
+| `auto_destroy` | Boolean | 关闭后是否自动销毁组件 |
+| `movable` | Boolean | 是否可拖动 |
+| `resizable` | Boolean | 是否可调整大小 |
+| `modal` | Boolean | 是否为模态（遮罩其他控件） |
+
+> **`archor` 取值说明**  
+> 支持九宫格定位：  
+> `'tl'`, `'tc'`, `'tr'`, `'cl'`, `'cc'`, `'cr'`, `'bl'`, `'bc'`, `'br'`  
+> 分别表示：左上、中上、右上、左中、居中、右中、左下、中下、右下
+
+---
+
+## 核心类：`bricks.Popup`
+
+继承自 `bricks.VBox`，提供完整的弹窗功能。
+
+### 构造函数：`constructor(opts)`
+
+#### 参数
+- `opts` (Object): 配置选项，合并默认配置使用。
+
+#### 内部属性初始化
+| 属性 | 类型 | 初始值 | 说明 |
+|------|------|--------|------|
+| `no_opened` | Boolean | `true` | 是否首次打开 |
+| `auto_task` | Task | `null` | 超时任务句柄 |
+| `issub` | Boolean | `false` | 是否依附于某个控件显示 |
+| `opened` | Boolean | `false` | 当前是否已打开 |
+| `content_box` | VBox | 实例 | 内容容器 |
+| `content_w` | Widget | `content_box` | 内容承载部件 |
+| `moving_w` | Widget | `this` | 可拖动目标（默认整个弹窗） |
+| `target_w` | Widget | `bricks.Body` | 目标绑定控件 |
+| `moving_status` | Boolean | `false` | 拖拽状态标志 |
+| `resize_status` | Boolean | `false` | 缩放状态标志 |
+
+#### 初始化流程
+1. 设置 CSS 类名为 `popup`
+2. 将自身置于顶层（z-index）
+3. 创建内容容器并添加到内部
+4. 绑定点击外部关闭事件（若启用 `auto_dismiss`）
+5. 启用拖动（`movable`）与缩放（`resizable`）
+6. 默认隐藏（`display: none`）
+7. 添加至 `Body` 容器
+8. 绑定点击以提升层级
+9. 若 `auto_open === true`，调用 `open()`
+10. 若有 `content`，监听 `opened` 事件加载内容
+
+---
+
+### 方法详解
+
+#### `load_content() → Promise<void>`
+异步加载配置中的 `content` 并渲染到内容区。
+
+```js
+async load_content(){
+  var w = await bricks.widgetBuild(this.content, this);
+  if (w){
+    this.set_dismiss_events(w);
+    this.content_w.clear_widgets();
+    this.content_w.add_widget(w);
+  }
+}
+```
+
+> ⚠️ 依赖 `bricks.widgetBuild()` 动态构建子控件树。
+
+---
+
+#### `set_dismiss_events(widget)`
+为指定控件绑定关闭事件。
+
+```js
+this.dismiss_events.forEach(ename => {
+  w.bind(ename, this.destroy.bind(this));
+});
+```
+
+> 示例：`dismiss_events: ['ok', 'cancel']` 会绑定这些事件触发销毁。
+
+---
+
+#### `bring_to_top()`
+将当前弹窗置顶（最高 z-index），更新全局 `toppopup` 引用。
+
+```js
+this.zindex = bricks.app.new_zindex();
+this.set_style('zIndex', this.zindex);
+bricks.app.toppopup = this;
+```
+
+---
+
+#### `popup_from_widget(from_w)`
+从指定控件位置智能定位弹窗（避开屏幕边缘）。
+
+##### 算法逻辑
+- 计算源控件中心坐标 `(ox, oy)`
+- 若源在左侧，则弹窗出现在右侧；否则出现在左侧
+- 若源在上方，则弹窗出现在下方；否则出现在上方
+- 边界检测防止溢出屏幕
+
+> 适用于 Tooltip 或 Context Menu 场景。
+
+---
+
+#### `setup_resizable()`
+启用可缩放功能，在右下角添加 SVG 缩放手柄。
+
+##### 子组件
+- `resizable_w`: SVG 图标（右下三角）
+
+##### 事件绑定
+- `mousedown` → `resize_start_pos`
+- `mousemove` → `resizing`
+- `mouseup` → `stop_resizing`
+
+---
+
+#### `resize_start_pos(e)`
+记录初始尺寸和鼠标位置，开始缩放。
+
+```js
+this.s_width = rect.width;
+this.s_height = rect.height;
+this.s_offsetX = e.clientX;
+this.s_offsetY = e.clientY;
+```
+
+---
+
+#### `resizing(e)`
+实时调整宽度和高度。
+
+```js
+cx = this.s_width + e.clientX - this.s_offsetX;
+cy = this.s_height + e.clientY - this.s_offsetY;
+this.set_style('width', cx + 'px');
+this.set_style('height', cy + 'px');
+```
+
+---
+
+#### `stop_resizing(e)`
+结束缩放操作，解绑全局事件。
+
+```js
+this.resize_status = false;
+bricks.Body.unbind('mousemove', this.resizing.bind(this));
+bricks.Body.unbind('mouseup', this.stop_resizing.bind(this));
+```
+
+---
+
+#### `positify_tl()`
+根据 `archor` 和屏幕尺寸计算并设置弹窗位置。
+
+##### 尺寸解析优先级
+1. `cwidth` / `cheight`（字符单位 × 字符大小）
+2. `width` / `height`（百分比或 px）
+3. 默认占屏 80%
+
+##### 锚点布局规则
+| 第一位（垂直） | 第二位（水平） |
+|----------------|----------------|
+| `t`: 顶部对齐   | `l`: 左对齐     |
+| `c`: 居中       | `c`: 居中       |
+| `b`: 底部对齐   | `r`: 右对齐     |
+
+> 返回 `{ top, left }` 像素坐标。
+
+---
+
+#### `setup_movable()`
+启用拖动功能，绑定 `mousedown` 和 `touchstart`。
+
+---
+
+#### `rec_start_pos(e)`
+记录拖动起点偏移量，并绑定移动与释放事件。
+
+```js
+this.offsetX = e.clientX - rect.left;
+this.offsetY = e.clientY - rect.top;
+```
+
+---
+
+#### `moving(e)`
+实时更新位置。
+
+```js
+cx = e.clientX - this.offsetX;
+cy = e.clientY - this.offsetY;
+this.set_style('left', cx + 'px');
+this.set_style('top', cy + 'px');
+```
+
+---
+
+#### `stop_moving(e)`
+停止拖动，解绑所有相关事件。
+
+---
+
+#### `click_outside(event)`
+点击弹窗外区域时关闭弹窗（仅当 `auto_dismiss` 为 `true` 时生效）。
+
+```js
+if (event.target != this.dom_element) this.dismiss();
+```
+
+---
+
+#### `open()`
+打开弹窗。
+
+##### 流程
+1. 若无父节点，加入 `app` 根容器
+2. 若是首次打开：
+   - 设置目标控件（`widget` 参数）
+   - 执行定位 `positify_tl()`
+3. 显示元素（`display: block`）
+4. 触发 `opened` 事件
+5. 设置超时关闭任务（如需）
+6. 若为模态，则禁用目标控件
+7. 提升至顶层
+
+---
+
+#### `dismiss()`
+关闭弹窗。
+
+##### 流程
+1. 若为模态，恢复目标控件可用状态
+2. 清除超时任务
+3. 隐藏元素（`display: none`）
+4. 触发 `dismissed` 事件
+5. 若 `auto_destroy === true`，执行 `destroy()`
+
+---
+
+#### `destroy()`
+彻底销毁组件。
+
+```js
+if (this.opened) this.dismiss();
+if (this.parent) {
+  this.parent.remove_widget(this);
+  this.parent = null;
+}
+```
+
+---
+
+#### `add_widget(w, i)`
+向内容区域添加控件，并自动绑定关闭事件。
+
+> 若 `auto_open` 为 `true`，则立即打开弹窗。
+
+---
+
+#### `remove_widget(w)` / `clear_widgets()`
+代理调用 `content_w` 的对应方法。
+
+---
+
+## 扩展类：`bricks.PopupWindow`
+
+继承自 `Popup`，模拟操作系统窗口，带有标题栏和控制按钮。
+
+### 构造函数特点
+```js
+opts.movable = true;
+opts.resizable = true;
+opts.auto_open = false; // 手动控制打开时机
+```
+
+#### 特有属性
+| 属性 | 说明 |
+|------|------|
+| `title_bar` | 标题栏容器（HBox） |
+| `tb_w` | 控制按钮栏（IconBar） |
+| `content_w` | 主内容区（Layout） |
+| `title_w` | 标题文本显示控件 |
+
+#### 内部结构
+1. **标题栏 (`titlebar`)**
+   - 图标（SVG）
+   - 控制按钮组（删除、最小化、全屏）
+   - 标题文本
+2. **填充层 (`Filler`)**
+   - 包含主内容区
+3. **内容区 (`Layout`)**
+   - 支持 Flex 布局
+
+#### 控制按钮功能
+| 按钮 | 功能 |
+|------|------|
+| `delete` | 调用 `destroy()` 销毁窗口 |
+| `minimize` | 调用 `win_minimize()` 最小化 |
+| `fullscreen` | 进入全屏模式 |
+
+---
+
+#### `win_minimize()`
+关闭窗口并将自身推入 `bricks.app.mwins` 数组，供后续恢复。
+
+```js
+this.dismiss();
+if (!this.auto_destroy) {
+  bricks.app.mwins.push(this);
+}
+```
+
+---
+
+#### `set_title(txt)`
+动态修改窗口标题。
+
+```js
+this.title_w.set_text(txt);
+```
+
+---
+
+## 工具类：`bricks.WindowsPanel`
+
+用于展示所有最小化的窗口列表，点击可恢复。
+
+### 构造函数行为
+- 固定宽高为 `80%`
+- 自动关闭、销毁
+- 不自动打开
+
+#### 数据绑定结构
+使用 `Cols` 组件渲染表格：
+
+```json
+{
+  "total": 3,
+  "rows": [
+    { "title": "Settings", "url": "...", "pos": 0 },
+    ...
+  ]
+}
+```
+
+每行包含图标、标题，点击触发 `del_window()`。
+
+---
+
+#### `del_window(event)`
+恢复指定位置的窗口并从列表中移除。
+
+```js
+var pos = event.params.pos;
+var w = bricks.app.mwins[pos];
+w.open(); // 恢复显示
+bricks.app.mwins.splice(pos, 1); // 删除记录
+this.dismiss(); // 关闭面板
+```
+
+---
+
+## 工厂注册
+
+```js
+bricks.Factory.register('Popup', bricks.Popup);
+bricks.Factory.register('PopupWindow', bricks.PopupWindow);
+```
+
+支持通过字符串类型动态创建组件实例。
+
+---
+
+## 静态辅助函数
+
+### `bricks.get_popupwindow_default_options()`
+
+返回专用于 `PopupWindow` 的默认配置，与普通 `Popup` 的区别在于：
+
+```diff
++ resizable: true
+```
+
+其余同 `get_popup_default_options()`。
+
+---
+
+## 使用示例
+
+### 创建简单弹窗
+```js
+let popup = new bricks.Popup({
+  content: {
+    widgettype: 'Text',
+    options: { text: 'Hello World!' }
+  },
+  archor: 'cc',
+  timeout: 3000
+});
+```
+
+### 创建应用窗口
+```js
+let win = new bricks.PopupWindow({
+  title: '用户设置',
+  icon: '/icons/settings.svg',
+  content: { ... },
+  auto_open: true
+});
+```
+
+### 显示窗口管理器
+```js
+let panel = new bricks.WindowsPanel();
+panel.open();
+```
+
+---
+
+## 注意事项
+
+1. **事件作用域问题**：大量使用 `.bind(this)`，注意性能影响。
+2. **内存泄漏风险**：未正确解绑事件可能导致残留监听器。
+3. **触摸设备兼容性**：支持 `touchstart/move/end`，但需测试跨平台表现。
+4. **z-index 管理**：依赖 `bricks.app.new_zindex()`，需保证唯一递增。
+5. **异步内容加载**：`load_content()` 为异步，注意加载顺序。
+
+---
+
+## 总结
+
+`bricks.Popup` 系列组件提供了强大而灵活的弹窗系统，具备以下核心能力：
+
+✅ 模态/非模态切换  
+✅ 自动定位与边界适配  
+✅ 拖拽移动 & 缩放  
+✅ 外部点击关闭  
+✅ 超时自动关闭  
+✅ 内容动态加载  
+✅ 窗口最小化管理  
+
+适合构建复杂的桌面风格 Web 应用界面。
+
+--- 
+
+> 文档版本：v1.0  
+> 最后更新：2025-04-05
\ No newline at end of file
diff --git a/aidocs/progressbar.md b/aidocs/progressbar.md
new file mode 100644
index 0000000..e91151c
--- /dev/null
+++ b/aidocs/progressbar.md
@@ -0,0 +1,150 @@
+# `bricks.ProgressBar` 技术文档
+
+```markdown
+# bricks.ProgressBar
+
+`bricks.ProgressBar` 是一个基于 `bricks.HBox` 的进度条组件，用于在用户界面中可视化显示任务的完成进度。它通过 CSS 样式控制外观，并支持动态设置当前进度值。
+
+---
+
+## 继承关系
+
+- **继承自**: `bricks.HBox`
+- **注册名称**: `'ProgressBar'`（通过 `bricks.Factory` 注册）
+
+---
+
+## 构造函数
+
+### `new ProgressBar(opts)`
+
+创建一个进度条实例。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `opts` | Object | 配置选项对象 |
+
+##### 可选配置项 (`opts`)
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `total_value` | Number | `100`（隐式） | 进度条的总值，用于计算百分比 |
+| `bar_cwidth` | Number | `2` | 进度条的高度（以字符行为单位），影响内部文本控件的高度 |
+
+> ⚠️ 注意：`total_value` 在当前代码中未被实际读取或存储，逻辑上应传入并在 `set_value` 中使用。
+
+#### 实现细节
+
+- 调用父类构造函数 `super(opts)`。
+- 设置容器的 CSS 类名为 `progress-container`。
+- 创建一个 `bricks.Text` 实例作为进度条填充部分：
+  - 初始文本为 `'0%'`
+  - 高度由 `bar_cwidth` 决定（默认为 2 行高）
+  - 添加 CSS 类 `progress-bar`
+- 将该文本控件添加到布局中。
+
+---
+
+## 方法
+
+### `set_value(v)`
+
+设置当前进度值并更新进度条的视觉表现。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `v` | Number | 当前进度值（应小于等于 `total_value`） |
+
+#### 实现逻辑
+
+> ❗ 存在 Bug：以下变量未定义或命名错误！
+
+```js
+var pzt = (current / total) * 100;
+pzt = Math.max(0, Math.min(100, percentage));
+```
+
+- `current` 和 `total` 未声明。
+- `percentage` 变量不存在，应为 `pzt`。
+- 正确逻辑应基于输入参数 `v` 和预设的 `total_value` 计算百分比。
+
+✅ **建议修正版本**：
+
+```js
+set_value(v) {
+    const total = this.total_value || 100;
+    let percentage = (v / total) * 100;
+    percentage = Math.max(0, Math.min(100, percentage));
+    this.text_w.set_style('width', percentage + '%');
+}
+```
+
+此外，应在构造函数中保存 `this.total_value = opts.total_value || 100;`。
+
+---
+
+## 事件
+
+当前组件未定义任何自定义事件。
+
+---
+
+## 样式类
+
+| CSS 类名 | 应用元素 | 用途 |
+|---------|----------|------|
+| `progress-container` | 容器（HBox） | 包裹整个进度条的外层样式 |
+| `progress-bar` | 文本控件（填充条） | 控制进度条填充部分的样式，通常配合 `width` 动态调整 |
+
+> 建议在 CSS 中定义 `.progress-bar` 为块级元素，具有背景色、过渡动画等效果。
+
+---
+
+## 使用示例
+
+```js
+const progressBar = new bricks.ProgressBar({
+    total_value: 200,
+    bar_cwidth: 3
+});
+
+// 添加到某个容器
+someContainer.add_widget(progressBar);
+
+// 更新进度
+progressBar.set_value(50);  // 显示 25%
+progressBar.set_value(100); // 显示 50%
+```
+
+---
+
+## 已知问题与改进建议
+
+1. ✅ **Bug**: `set_value` 方法中使用了未定义的变量 `current`, `total`, `percentage`。
+2. ✅ **缺少属性初始化**：`total_value` 应在构造函数中保存。
+3. 🔧 **功能扩展建议**：
+   - 支持显示百分比数字文本。
+   - 提供 `get_value()` 方法。
+   - 支持事件通知（如 `onchange`）。
+4. 🎨 **样式建议**：
+   - 使用 Flexbox 布局确保进度条拉伸一致。
+   - 添加边框和圆角提升视觉体验。
+
+---
+
+## 注册信息
+
+通过工厂注册，可在模板或动态创建中使用字符串标识：
+
+```js
+bricks.Factory.register('ProgressBar', bricks.ProgressBar);
+```
+
+--- 
+
+> **备注**：请修复 `set_value` 中的变量引用错误以确保组件正常工作。
+```
\ No newline at end of file
diff --git a/aidocs/qaframe.md b/aidocs/qaframe.md
new file mode 100644
index 0000000..eccaa05
--- /dev/null
+++ b/aidocs/qaframe.md
@@ -0,0 +1,343 @@
+# `bricks.QAFrame` 技术文档
+
+> 一个基于 WebSocket 的问答交互框架组件，支持多媒体课件展示、题目呈现与用户答案提交。
+
+---
+
+## 概述
+
+`bricks.QAFrame` 是 `bricks` UI 框架中的一个复合组件类，继承自 `bricks.VBox`。它用于构建一个完整的**问答互动界面**，通过 WebSocket 与后端服务通信，支持以下功能：
+
+- 展示多媒体课件（视频、音频、图片、Markdown）
+- 显示问题并接收用户输入（文本或语音）
+- 控制答题流程（开始确认、题目切换、结果反馈等）
+
+该组件广泛适用于在线教育、智能测评和互动学习场景。
+
+---
+
+## 继承关系
+
+```
+bricks.QAFrame → bricks.VBox → bricks.Widget
+```
+
+---
+
+## 构造函数
+
+```js
+new bricks.QAFrame(options)
+```
+
+### 参数：`options` (Object)
+
+| 属性名         | 类型     | 必填 | 描述 |
+|----------------|----------|------|------|
+| `ws_url`       | String   | 是   | WebSocket 连接地址 |
+| `ws_params`    | Object   | 否   | WebSocket 查询参数对象，将被序列化为 URL 查询字符串 |
+| `title`        | String   | 否   | 页面标题（未在代码中使用，保留字段） |
+| `description`  | String   | 否   | 描述信息（未在代码中使用，保留字段） |
+| `courseware`   | Object   | 否   | 初始课件配置，结构见下文 |
+
+#### `courseware` 子属性
+
+| 属性名    | 类型     | 可选值                     | 描述 |
+|-----------|----------|----------------------------|------|
+| `type`    | String   | `"audio"`, `"video"`, `"image"`, `"markdown"` | 媒体类型 |
+| `url`     | String   | -                          | 资源 URL |
+| `timeout` | Number   | 秒数，0 表示无超时         | 自动跳转时间 |
+
+> 示例：
+> ```js
+> courseware: {
+>   type: 'video',
+>   url: '/media/intro.mp4',
+>   timeout: 30
+> }
+> ```
+
+---
+
+## 内部结构布局
+
+`QAFrame` 使用垂直布局容器（VBox），包含三个主要区域：
+
+| 区域      | 组件          | 功能说明 |
+|-----------|---------------|----------|
+| `top_w`   | `HBox`        | 顶部工具栏区域（可显示题号） |
+| `main_w`  | `Filler`      | 主内容区，动态加载课件或问题 |
+| `bottom_w`| `HBox`        | 底部操作区，放置按钮或输入控件 |
+
+---
+
+## WebSocket 通信协议
+
+`QAFrame` 通过内置的 `bricks.WebSocket` 实例与服务器进行双向通信。
+
+### WebSocket 初始化
+
+自动拼接 `ws_params` 成查询字符串：
+
+```js
+const url = this.ws_url + '?' + new URLSearchParams(this.ws_params).toString();
+this.ws = new bricks.WebSocket({ ws_url: url });
+```
+
+### 监听事件绑定
+
+| 事件名           | 回调方法             | 触发时机 |
+|------------------|----------------------|---------|
+| `onopen`         | `start_question_answer()` | WebSocket 连接建立时 |
+| `onquestion`     | `show_question(d)`   | 收到新问题数据 |
+| `oncourseware`   | `show_courseware(d)` | 收到课件数据 |
+| `onaskstart`     | `show_conform(d)`    | 请求用户确认开始 |
+
+> ⚠️ 注意：`oncourseware` 被重复绑定三次 —— 此为冗余代码，建议优化。
+
+---
+
+## 接收消息格式（Server → Client）
+
+由 WebSocket 推送的消息通过 `data` 字段传递，`type` 标识消息类型。
+
+| 编号 | 类型            | `data` 结构 | 说明 |
+|------|------------------|-------------|------|
+| 1    | `courseware`     | `{ type, url }` | 播放指定类型的媒体资源 |
+| 2    | `askready`       | `{ total_q, cur_q }` | 提示准备开始第几题 |
+| 3    | `question`       | `{ q_desc, total_q, cur_q }` | 显示具体问题 |
+| 4    | `result`         | `{ total_q, correct_cnt, error_cnt }` | 显示答题结果统计 |
+| 5    | `error_list`     | `{ error_cnt, rows: [...] }` | 错误详情列表 |
+
+### `error_list.rows[]` 元素结构
+
+| 字段        | 类型   | 说明 |
+|-------------|--------|------|
+| `pos`       | Number | 题目位置索引 |
+| `q_desc`    | String | 题干描述 |
+| `your_a`    | String | 用户答案 |
+| `corrent_a` | String | 正确答案 |
+| `error_desc`| String | 错误原因说明 |
+
+---
+
+## 发送消息格式（Client → Server）
+
+| 编号 | 类型             | `data` 值 | 触发方式 |
+|------|-------------------|-----------|----------|
+| 1    | `qa_start`        | `null` 或 `{ d: "test data", v: 100 }` | 点击“开始”或连接打开时自动发送 |
+| 2    | `conform_start`   | `null` | 用户点击“Start?”按钮触发 |
+| 3    | `text_answer`     | `{ texta: "用户输入内容" }` | 文本输入框失去焦点时 |
+| 4    | `audio_answer`    | Base64 编码的音频 Blob | 录音结束时自动发送 |
+
+> 示例：
+> ```js
+> { type: 'text_answer', data: 'Hello world' }
+> { type: 'audio_answer', data: 'base64:...' }
+> ```
+
+---
+
+## 核心方法说明
+
+### `show_question(d)`
+
+显示一道新问题。
+
+#### 参数
+- `d`: `{ q_desc, total_q, cur_q }`
+
+#### 行为
+- 更新顶部题号显示（需确保已创建 `qtotal_w` 和 `qcur_w`，当前代码缺失定义）
+- 使用 `widgetBuild` 解析 `q_desc` 内容生成子组件
+- 添加至主区域
+
+> ✅ 支持富内容渲染（如 HTML、自定义组件）
+
+---
+
+### `show_courseware(d)`
+
+播放指定课件资源。
+
+#### 参数
+- `d`: `{ type, url }`
+
+#### 支持类型
+| 类型       | 组件               | 特性 |
+|------------|--------------------|------|
+| `video`    | `bricks.Video`     | 全屏自动播放 |
+| `audio`    | `bricks.AudioPlayer` | 自动播放 |
+| `image`    | `bricks.Image`     | 全屏展示 |
+| `markdown` | `bricks.MdWidget`  | 加载远程 `.md` 文件 |
+
+> 所有组件均设置宽高为 `100%`，适应容器。
+
+---
+
+### `show_conform(d)`
+
+显示“是否开始”确认按钮。
+
+#### 行为
+- 清空主区域
+- 添加一个标签为 `"Start ?"` 的按钮
+- 绑定点击事件调用 `start_question_answer()`
+
+---
+
+### `start_question_answer()`
+
+向服务端发送启动信号。
+
+```js
+this.ws.send({
+  type: 'qa_start',
+  data: { d: 'test data', v: 100 }
+});
+```
+
+通常由 `WebSocket.onopen` 或用户点击触发。
+
+---
+
+### `conform_start()`
+
+发送用户确认开始指令。
+
+```js
+this.ws.send({
+  type: 'conform_start',
+  data: null
+});
+```
+
+---
+
+### `send_text_answer(e)`
+
+处理文本答案提交。
+
+#### 参数
+- `e.data.texta`: 用户输入文本
+
+#### 流程
+- 获取输入值
+- 发送 `text_answer` 消息
+
+> 绑定于 `StrInput` 的 `blur` 事件（失焦即提交）
+
+---
+
+### `send_audio_answer(e)`
+
+异步处理录音答案提交。
+
+#### 参数
+- `e.data.audio`: Blob 音频数据
+
+#### 流程
+1. 将 Blob 转为 Base64 字符串（依赖 `blobToBase64` 函数）
+2. 发送 `audio_answer` 消息
+
+> ⚠️ 注意：`send_audio_data` 方法未定义，应为笔误，实际应为 `send_audio_answer`
+
+---
+
+### `build_input_widgets()`
+
+构建底部输入控件区。
+
+#### 创建组件
+- `StrInput`: 文本输入框（name=`texta`，样式填充）
+- `AudioRecorder`: 语音录制按钮（带图标动画）
+
+#### 事件绑定
+- 文本框失焦 → `send_text_answer`
+- 录音结束 → `send_audio_answer`（原写错为 `send_audio_data`）
+
+> ❗ 注释部分包含图像/视频采集功能预留接口（SVG 图标），目前未启用。
+
+---
+
+### `play_course()`
+
+【未使用】根据 `this.courseware` 播放初始课程内容。
+
+> 当前逻辑中未调用此方法。若需启用，应在构造函数中补充调用。
+
+---
+
+### `build_startbtn()`
+
+构建底部“press to start”按钮。
+
+> 当前未在构造函数中调用，可能用于手动控制启动流程。
+
+---
+
+## 工厂注册
+
+```js
+bricks.Factory.register('QAFrame', bricks.QAFrame);
+```
+
+允许通过工厂模式按名称创建实例：
+
+```js
+bricks.create({ type: 'QAFrame', ws_url: 'ws://localhost:8080' });
+```
+
+---
+
+## 使用示例
+
+```html
+<div id="qa-container"></div>
+<script>
+  const qa = new bricks.QAFrame({
+    ws_url: 'ws://example.com/ws/qa',
+    ws_params: {
+      session_id: 'abc123',
+      user_id: 'u456'
+    },
+    courseware: {
+      type: 'video',
+      url: '/intro.mp4',
+      timeout: 15
+    }
+  });
+
+  document.getElementById('qa-container').appendChild(qa.root());
+</script>
+```
+
+---
+
+## 已知问题与改进建议
+
+| 问题 | 描述 | 建议 |
+|------|------|------|
+| `qtotal_w` / `qcur_w` 未定义 | `show_question` 中尝试调用 `.set_text()`，但未初始化这些 widget | 应在构造函数中创建并加入 `top_w` |
+| `oncourseware` 多次绑定 | 同一事件监听器重复注册三次 | 保留一次即可 |
+| `send_audio_data` 调用错误 | `bind('record_ended')` 指向不存在的方法 | 改为 `this.send_audio_answer.bind(this)` |
+| `play_course()` 未调用 | 初始化课件无法自动播放 | 在合适时机调用（如构造末尾判断是否存在 `courseware`） |
+| `StrInput` 工厂调用不明确 | `StrInput({...})` 不符合常规语法 | 应为 `new bricks.StrInput(...)` 或使用 `widgetBuild` |
+
+---
+
+## 总结
+
+`bricks.QAFrame` 是一个功能完整、结构清晰的互动问答组件，具备以下优势：
+
+✅ 支持多种媒体格式  
+✅ 实时双向通信  
+✅ 模块化设计便于扩展  
+✅ 适合嵌入式教学系统
+
+建议修复上述问题以提升稳定性和可维护性。
+
+--- 
+
+*文档版本：v1.0*  
+*最后更新：2025年4月*
\ No newline at end of file
diff --git a/aidocs/recorder.md b/aidocs/recorder.md
new file mode 100644
index 0000000..896fa88
--- /dev/null
+++ b/aidocs/recorder.md
@@ -0,0 +1,410 @@
+# `bricks.MediaRecorder` 技术文档
+
+## 概述
+
+`bricks.MediaRecorder` 是一个基于浏览器 `MediaRecorder API` 的通用媒体录制组件，继承自 `bricks.Popup`。它提供了统一的界面和控制逻辑，支持音频、视频以及特定 DOM 元素（如 `<video>`）的录制功能。
+
+通过继承机制，该类派生出多个具体实现：
+
+- `WidgetRecorder`：录制指定页面中的媒体元素（如 `<video>` 或 `<audio>`）
+- `SysAudioRecorder`：录制系统麦克风输入（音频流），并自动转换 WebM 为 WAV 格式
+- `SysVideoRecorder`：录制摄像头及麦克风输入（音视频流），实时预览画面
+- `SysCamera`：仅拍照模式，用于从摄像头抓取单帧图像
+
+所有子类均通过 `bricks.Factory` 注册，便于在应用中动态创建。
+
+---
+
+## 基础类：`bricks.MediaRecorder`
+
+### 继承关系
+```js
+class bricks.MediaRecorder extends bricks.Popup
+```
+
+### 构造函数
+```js
+constructor(opts)
+```
+
+#### 参数
+| 参数名 | 类型 | 必需 | 默认值 | 说明 |
+|-------|------|------|--------|------|
+| `opts.fps` | Number | 否 | `30` | 帧率（每秒更新次数），用于时间显示刷新频率 |
+
+#### 初始化内容
+- 设置任务周期：`this.task_period = 1 / fps`
+- 创建 UI 组件：
+  - `preview`: 预览区域（VBox）
+  - `controls`: 控制栏（HBox）
+    - `toggle_record`: 开始/停止按钮（SVG 图标）
+    - `timepass`: 显示已录制时间（格式：`HH:MM:SS`）
+    - `filler`: 弹性填充空间
+    - `cancel`: 取消按钮（删除图标）
+- 绑定事件：
+  - `toggle_record.click` → `switch_record()`
+  - `cancel.click` → `cancel_record()`
+- 初始化状态：
+  - `record_status = 'standby'`
+  - 初始禁用录制按钮
+- 调度 `open_recorder()` 在 0.1 秒后执行（异步准备设备）
+
+---
+
+### 属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `fps` | Number | 每秒帧数，决定 UI 更新频率 |
+| `task_period` | Number | 定时任务间隔（秒） |
+| `task` | TaskHandle | 当前运行的时间更新定时器 |
+| `pic_task` | TaskHandle | （仅视频）图像捕获定时器 |
+| `stream` | MediaStream | 获取到的媒体流 |
+| `mediaRecorder` | MediaRecorder | 浏览器原生录制实例 |
+| `recordedChunks` | Array<Blob> | 存储录制过程中产生的数据块 |
+| `mimetype` | String | 媒体 MIME 类型（如 `'audio/wav'`, `'video/mp4'`） |
+| `normal_stop` | Boolean | 是否正常结束录制（防止重复触发） |
+| `record_status` | String | 状态：`'standby'` 或 `'recording'` |
+| `start_time` | Number | 录制开始的时间戳（毫秒） |
+| `time_diff` | String | 当前录制时长字符串（`HH:MM:SS`） |
+
+---
+
+### 方法
+
+#### `tick_task()`
+定时更新录制时间显示。
+
+```js
+tick_task()
+```
+
+- 使用 `schedule_once` 循环调用自身，间隔为 `this.task_period`
+- 调用 `bricks.timeDiff(this.start_time)` 计算经过时间
+- 更新 `this.timepass` 文本
+
+> ⚠️ 注意：必须手动取消任务以避免内存泄漏。
+
+---
+
+#### `async switch_record()`
+切换录制状态（开始或停止录制）。
+
+```js
+switch_record()
+```
+
+行为根据当前 `record_status` 决定：
+
+| 状态 | 动作 |
+|------|------|
+| `'standby'` | 调用 `start_recorder()`，图标变为“停止” |
+| `'recording'` | 调用 `stop_recorder()`，图标恢复为“开始” |
+
+---
+
+#### `cancel_record()`
+取消当前录制操作，关闭资源并关闭弹窗。
+
+```js
+cancel_record()
+```
+
+等价于调用 `close_recorder()`。
+
+---
+
+#### `async open_recorder()`
+**虚方法**：由子类重写以打开具体的媒体源。
+
+```js
+open_recorder()
+```
+
+> 默认实现为空，仅输出调试日志。
+
+子类应在此方法中：
+- 请求用户权限（如麦克风/摄像头）
+- 获取 `MediaStream`
+- 设置 `this.stream`
+- 解除录制按钮禁用状态
+
+---
+
+#### `async start_recorder()`
+启动实际录制流程。
+
+##### 步骤：
+1. 设置 `normal_stop = false`
+2. 实例化 `MediaRecorder` 并绑定事件：
+   - `ondataavailable`: 收集数据块到 `recordedChunks`
+   - `onstop`: 处理最终文件生成与事件分发
+3. 记录 `start_time`
+4. 启动定时器更新时间显示
+5. 调用 `mediaRecorder.start()`
+6. 触发 `record_started` 事件
+
+##### 事件分发
+- `record_started`: 录制开始时触发
+
+---
+
+#### `async blob_convert(blob)`
+**可扩展方法**：允许子类对录制结果 Blob 进行格式转换。
+
+```js
+blob_convert(blob) → Promise<Blob>
+```
+
+默认直接返回原始 Blob。
+
+> 示例：`SysAudioRecorder` 中将 WebM 转换为 WAV。
+
+---
+
+#### `stop_recorder()`
+停止录制，并标记为正常终止。
+
+##### 行为：
+- 设置 `normal_stop = true`
+- 更新时间显示
+- 调用 `mediaRecorder.stop()`
+- 调用 `close_recorder()`
+
+---
+
+#### `close_recorder()`
+清理资源并关闭弹窗。
+
+##### 清理项：
+- 取消 `task` 和 `pic_task`（如有）
+- 停止 `mediaRecorder`（若存在）
+- 停止 `stream` 所有轨道
+- 调用 `dismiss()` 关闭弹窗
+
+> 若正在录制，会强制中断。
+
+---
+
+## 子类详解
+
+---
+
+### `bricks.WidgetRecorder`
+
+> 录制页面中某个媒体元素（如 `<video>` 或 `<audio>`）
+
+#### 继承链
+```js
+class WidgetRecorder extends MediaRecorder
+```
+
+#### `open_recorder()`
+- 根据 `opts.widgetid` 查找目标组件
+- 检查其 DOM 标签类型：
+  - `<video>` → `mimetype = 'video/mp4'`
+  - `<audio>` → `mimetype = 'audio/wav'`
+- 调用 `captureStream()` 获取流
+- 启用录制按钮
+
+⚠️ 错误处理：非媒体元素抛出异常
+
+---
+
+### `bricks.SysAudioRecorder`
+
+> 录制麦克风输入，支持 WebM → WAV 自动转换
+
+#### 继承链
+```js
+class SysAudioRecorder extends MediaRecorder
+```
+
+#### `open_recorder()`
+- 请求麦克风权限（`getUserMedia({ audio: true })`）
+- 设置 `mimetype = 'audio/webm'`
+- 获取音频流并启用按钮
+
+#### `blob_convert(webmBlob)`
+将 WebM 编码的音频解码为 PCM，再编码为标准 WAV 格式 Blob。
+
+##### 流程：
+1. `webmBlob.arrayBuffer()` → 获取二进制数据
+2. 使用 `AudioContext.decodeAudioData()` 解码为 `AudioBuffer`
+3. 调用 `encodeWAV()` 生成 WAV 文件头 + 数据
+4. 返回新的 `Blob(type='audio/wav')`
+
+#### `encodeWAV(audioBuffer)`
+手动构建 WAV 文件二进制结构，包含 RIFF 头信息。
+
+| 参数 | 值 |
+|------|----|
+| 采样率 | 来自 `audioBuffer.sampleRate` |
+| 声道数 | `audioBuffer.numberOfChannels` |
+| 位深 | 16-bit PCM |
+| 格式 | 小端序（little-endian） |
+
+使用 `DataView` 写入头部字段。
+
+#### `interleave(left, right)`
+交错左右声道数据，生成立体声 PCM 数组。
+
+#### `writeString(view, offset, string)`
+辅助函数：向 `DataView` 写入 ASCII 字符串。
+
+---
+
+### `bricks.SysVideoRecorder`
+
+> 录制摄像头+麦克风，带实时预览
+
+#### 继承链
+```js
+class SysVideoRecorder extends MediaRecorder
+```
+
+#### `open_recorder()`
+- 请求音视频权限：`{ audio: true, video: true }`
+- 设置 `mimetype = 'video/mp4'`
+- 创建 `ImageCapture(track)` 对象用于逐帧捕获
+- 添加 `bricks.Image` 到预览区
+- 启动 `show_picture()` 循环任务
+
+#### `show_picture()`
+- 调用 `imageCapture.takePhoto()` 获取当前帧 Blob
+- 转换为 Data URL 并设置给 `imgw`
+- 创建 `File` 对象供后续使用
+- 递归调度下一次拍摄
+
+> 实现了类似“摄像机取景器”的效果
+
+#### `close_recorder()`
+重写以额外清理 `pic_task`。
+
+---
+
+### `bricks.SysCamera`
+
+> 专用拍照工具，从摄像头抓拍一张照片
+
+#### 继承链
+```js
+class SysCamera extends SysVideoRecorder
+```
+
+#### `switch_record()`
+重写行为为“拍照”而非录制：
+
+##### 动作：
+- 阻止事件冒泡（`event.stopPropagation()`）
+- 停止 `pic_task`
+- 设置 `task_period = 0` 防止继续更新
+- 分发 `shot` 事件，携带：
+  ```js
+  {
+    url: this.dataurl,   // 图像 Data URL
+    file: this.imgfile   // 图像 File 对象
+  }
+  ```
+- 调用 `close_recorder()` 关闭
+
+> 不进行任何视频录制，仅抓取一帧
+
+---
+
+## 工厂注册
+
+以下类通过 `bricks.Factory` 注册，可在配置中通过名称实例化：
+
+```js
+bricks.Factory.register('SysCamera', bricks.SysCamera);
+bricks.Factory.register('WidgetRecorder', bricks.WidgetRecorder);
+bricks.Factory.register('SysAudioRecorder', bricks.SysAudioRecorder);
+bricks.Factory.register('SysVideoRecorder', bricks.SysVideoRecorder);
+```
+
+示例使用方式（假设框架支持）：
+```json
+{
+  "type": "SysAudioRecorder",
+  "opts": {
+    "fps": 25
+  }
+}
+```
+
+---
+
+## 事件列表
+
+| 事件名 | 触发时机 | 传递数据 |
+|--------|----------|---------|
+| `record_started` | 录制开始时 | 无 |
+| `record_end` | 录制正常结束 | `{ url: string, file: File }` |
+| `shot` | （SysCamera）拍照完成 | `{ url: string, file: File }` |
+
+> 使用 `this.dispatch(eventName, data)` 触发
+
+---
+
+## 工具函数依赖
+
+| 函数 | 来源 | 用途 |
+|------|------|------|
+| `bricks_resource(path)` | 全局函数 | 解析静态资源路径 |
+| `schedule_once(fn, delay)` | 全局函数 | 延迟执行函数（支持取消） |
+| `bricks.timeDiff(timestamp)` | 工具模块 | 将时间戳差值转为 `HH:MM:SS` 字符串 |
+| `bricks.getWidgetById(id, app)` | 框架 API | 根据 ID 获取组件实例 |
+
+---
+
+## 使用示例
+
+### 启动音频录制
+```js
+const recorder = new bricks.SysAudioRecorder({
+  fps: 30
+});
+recorder.bind('record_end', (data) => {
+  console.log('录音完成:', data.file);
+  const audio = document.createElement('audio');
+  audio.src = data.url;
+  audio.controls = true;
+  document.body.appendChild(audio);
+});
+recorder.present(); // 显示录制界面
+```
+
+### 抓拍摄像头照片
+```js
+const camera = new bricks.SysCamera();
+camera.bind('shot', ({ file }) => {
+  console.log('照片已拍摄:', file);
+});
+camera.present();
+```
+
+---
+
+## 注意事项
+
+1. **权限请求**：`getUserMedia` 需要在安全上下文（HTTPS）中运行，且用户需授权。
+2. **兼容性**：`MediaRecorder` 在部分旧浏览器中不支持或需前缀。
+3. **内存管理**：长时间录制可能导致大量 `recordedChunks` 占用内存，建议限制最大时长。
+4. **格式支持**：不同浏览器支持的 `mimeType` 不同，应做检测回退。
+5. **跨域问题**：`captureStream()` 对 `<video>` 要求同源或 CORS 允许。
+
+---
+
+## 总结
+
+`bricks.MediaRecorder` 提供了一个模块化、可扩展的媒体录制架构，适用于多种场景：
+
+| 类 | 用途 | 输出格式 |
+|-----|------|---------|
+| `WidgetRecorder` | 录屏（特定元素） | MP4 / WAV |
+| `SysAudioRecorder` | 录音 | WAV（经转换） |
+| `SysVideoRecorder` | 录像 | MP4 |
+| `SysCamera` | 拍照 | JPEG |
+
+结合 `bricks` 框架的组件系统与事件机制，可轻松集成至可视化编辑器或交互式应用中。
\ No newline at end of file
diff --git a/aidocs/registerfunction.md b/aidocs/registerfunction.md
new file mode 100644
index 0000000..9a3b43b
--- /dev/null
+++ b/aidocs/registerfunction.md
@@ -0,0 +1,183 @@
+# Bricks RegisterFunction 模块技术文档
+
+---
+
+## 概述
+
+`RegisterFunction` 是 `bricks` 命名空间下的一个轻量级函数注册与管理类，用于在全局环境中注册、存储和获取函数。它提供了一种集中式的方式来管理可复用或动态调用的函数，适用于插件系统、事件处理器注册、模块化功能扩展等场景。
+
+该模块通过 `bricks.RF` 实例暴露给全局使用，确保函数注册的统一访问接口。
+
+---
+
+## 代码结构
+
+```javascript
+var bricks = window.bricks || {};
+
+class RegisterFunction {
+    constructor() {
+        this.rfs = {};
+    }
+
+    register(n, f) {
+        this.rfs[n] = f;
+    }
+
+    get(n) {
+        try {
+            return this.rfs[n];
+        } catch (e) {
+            return null;
+        }
+    }
+}
+
+bricks.RF = new RegisterFunction();
+```
+
+---
+
+## 核心类：`RegisterFunction`
+
+### 构造函数 `constructor()`
+
+初始化一个空的对象 `this.rfs`，用于存储注册的函数。
+
+#### 示例：
+```js
+const rf = new RegisterFunction(); // this.rfs = {}
+```
+
+---
+
+### 方法：`register(n, f)`
+
+将一个函数 `f` 注册到名称 `n` 下。
+
+#### 参数：
+- `n` (string | number): 函数的唯一标识名称（键名）。
+- `f` (Function): 要注册的函数。
+
+#### 行为：
+- 将 `f` 存储在 `this.rfs` 对象中，以 `n` 作为键。
+- 若已存在同名键，则覆盖原值。
+
+#### 示例：
+```js
+function greet() {
+    console.log("Hello!");
+}
+
+bricks.RF.register('greet', greet);
+```
+
+---
+
+### 方法：`get(n)`
+
+根据名称 `n` 获取已注册的函数。
+
+#### 参数：
+- `n` (string | number): 要获取的函数的名称。
+
+#### 返回值：
+- 如果存在对应的函数，返回该函数；
+- 如果不存在或发生异常，返回 `null`。
+
+> ⚠️ 注意：尽管 `try-catch` 被使用，但在 JavaScript 中直接访问对象属性不会抛出异常（除非对象被冻结或有 getter 抛错）。因此这里的 `try-catch` 属于防御性编程，实际多数情况下非必需。
+
+#### 示例：
+```js
+const greetFn = bricks.RF.get('greet');
+if (greetFn) {
+    greetFn(); // 输出: Hello!
+}
+```
+
+---
+
+## 全局实例：`bricks.RF`
+
+通过以下语句创建并暴露全局唯一的 `RegisterFunction` 实例：
+
+```js
+bricks.RF = new RegisterFunction();
+```
+
+此实例可在全局范围内通过 `bricks.RF` 访问，实现跨模块的函数注册与调用。
+
+---
+
+## 使用示例
+
+### 注册多个函数
+```js
+bricks.RF.register('log', msg => console.log(msg));
+bricks.RF.register('add', (a, b) => a + b);
+```
+
+### 调用已注册函数
+```js
+const log = bricks.RF.get('log');
+log('This is a test message.');
+
+const add = bricks.RF.get('add');
+console.log(add(2, 3)); // 输出: 5
+```
+
+### 处理未注册函数
+```js
+const unknown = bricks.RF.get('unknown');
+console.log(unknown); // 输出: null
+```
+
+---
+
+## 设计特点
+
+| 特性 | 说明 |
+|------|------|
+| **轻量** | 仅包含两个核心方法，无外部依赖。 |
+| **易用** | 接口简洁，便于集成到现有项目中。 |
+| **容错处理** | `get()` 方法包含异常捕获，增强健壮性。 |
+| **可扩展** | 可基于此类构建更复杂的注册中心（如带命名空间、生命周期管理等）。 |
+
+---
+
+## 注意事项
+
+1. **命名冲突**：注册时使用唯一名称，避免覆盖重要函数。
+2. **类型检查缺失**：当前未对传入的 `f` 是否为函数进行校验，建议调用前自行验证。
+3. **性能考虑**：底层基于普通对象存储，适合中小型注册场景；高频读写可考虑 `Map` 结构优化。
+
+---
+
+## 改进建议（可选）
+
+```js
+// 增强版 register：增加函数类型校验
+register(n, f) {
+    if (typeof f !== 'function') {
+        throw new Error(`Expected a function, but got ${typeof f}`);
+    }
+    this.rfs[n] = f;
+}
+
+// 或使用 Map 提升性能（尤其在大量条目时）
+this.rfs = new Map();
+register(n, f) { this.rfs.set(n, f); }
+get(n) { return this.rfs.get(n) || null; }
+```
+
+---
+
+## 版本信息
+
+- 初始版本：1.0
+- 作者：Bricks Framework Team
+- 兼容环境：现代浏览器（支持 ES6 Class）
+
+--- 
+
+> 📌 提示：本模块是 `bricks` 工具库的基础组件之一，推荐与其他模块配合使用以发挥最大效能。
\ No newline at end of file
diff --git a/aidocs/rtc.md b/aidocs/rtc.md
new file mode 100644
index 0000000..dfd6cb4
--- /dev/null
+++ b/aidocs/rtc.md
@@ -0,0 +1,435 @@
+# Bricks WebRTC 通信框架技术文档
+
+本文档描述了 `bricks` 框架中用于实现点对点（P2P）实时音视频通信的核心模块，包括：
+
+- `bricks.VideoBox`：用于播放媒体流的视频组件。
+- `bricks.Signaling`：信令服务客户端，通过 WebSocket 与服务器通信。
+- `bricks.RTCP2PConnect`：基于 WebRTC 的 P2P 连接管理器。
+
+---
+
+## 1. `bricks.VideoBox`
+
+一个封装了 `<video>` 元素的 JavaScript 组件，用于显示媒体流（如摄像头或屏幕共享流）。
+
+### 类定义
+```js
+class bricks.VideoBox extends bricks.JsWidget
+```
+
+### 方法
+
+#### `create()`
+创建并初始化 `<video>` DOM 元素，并设置自动播放和静音属性。
+
+**行为：**
+- 创建 `video` 元素。
+- 设置 `autoplay` 和 `muted` 属性为 `true`。
+
+> ⚠️ 注意：由于现代浏览器的安全策略，`autoplay` 只能在用户交互后生效，且必须配合 `muted` 才能无提示播放。
+
+#### `get_stream() → MediaStream`
+获取当前绑定到该视频元素的媒体流。
+
+**返回值：**
+- `{MediaStream}` 当前播放的媒体流对象。
+
+#### `set_stream(stream: MediaStream)`
+将指定的媒体流绑定到 `<video>` 元素上进行播放。
+
+**参数：**
+- `stream`: `{MediaStream}` 要播放的媒体流。
+
+**行为：**
+- 将 `stream` 赋值给内部变量 `this.stream`。
+- 设置 `this.dom_element.srcObject = stream`，触发视频播放。
+
+---
+
+## 2. `bricks.Signaling`
+
+信令客户端类，负责与信令服务器建立 WebSocket 连接，处理登录、心跳、消息收发及会话分发。
+
+### 构造函数
+```js
+new bricks.Signaling(opts)
+```
+
+**参数 `opts`：**
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `signaling_url` | `String` | WebSocket 信令服务器地址 |
+| `info` | `Object` | 客户端信息（如用户 ID、设备信息等），在发送数据时附加为 `msgfrom` 字段 |
+| `connect_opts` | `Object` | 传递给后续连接模块的通用配置选项 |
+| `onclose` | `Function` | WebSocket 关闭时的回调函数 |
+| `onopen` | `Function` | WebSocket 成功打开时的回调函数（可选） |
+| `onlogin` | `Function(onlinePeers)` | 登录成功后接收在线用户列表的回调 |
+| `heartbeat_period` | `Number` | 心跳周期（秒），若不设则不启用 |
+
+### 属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `socket` | `WebSocket` | 当前 WebSocket 实例 |
+| `peers` | `Object` | 存储当前在线用户的映射表（key: peer.id） |
+| `sessions` | `Object` | 已建立的会话记录（未使用） |
+| `handlers` | `Object` | 每个会话 ID 对应的消息处理器 |
+| `sessionhandlers` | `Object` | 按会话类型注册的处理器构造函数 |
+| `hb_task` | `TaskHandle` | 心跳定时任务句柄（由 `schedule_once` 返回） |
+| `heartbeat_period` | `Number` | 心跳间隔时间（秒） |
+
+### 方法
+
+#### `init_websocket()`
+初始化 WebSocket 连接：
+- 使用 `bricks.app.get_session()` 获取会话凭证作为子协议。
+- 绑定事件监听器：
+  - `onmessage` → `signaling_recvdata`
+  - `onopen` → `login`
+  - `onclose` / `onerror` → `reconnect`
+
+#### `reconnect()`
+WebSocket 断开后的处理逻辑：
+- 清除心跳任务。
+- 触发 `onclose` 回调。
+- **注意：当前未实现自动重连机制。**
+
+#### `signaling_recvdata(event)`
+异步处理从 WebSocket 接收到的数据包。
+
+**流程：**
+1. 解析 JSON 数据。
+2. 若包含 `data.session`，查找对应会话处理器：
+   - 若首次收到，则根据 `sessiontype` 实例化对应的处理器类。
+   - 注册该会话的 `recvdata_handler`。
+3. 否则调用默认 `recvdata_handler` 处理全局消息。
+
+#### `add_handler(key, handler)`
+注册某个 `sessionid` 的消息处理器。
+
+#### `add_sessionhandler(sessiontype, handlerClass)`
+注册某种会话类型的处理器类（构造函数）。例如：
+```js
+signaling.add_sessionhandler('p2p', bricks.RTCP2PConnect);
+```
+
+#### `recvdata_handler(data)`
+默认消息处理器，处理非会话级消息。
+
+**支持的消息类型：**
+- `online`: 更新在线用户列表，并触发 `onlogin(online)` 回调。
+
+> ❗ 未处理其他消息类型时仅打印日志。
+
+#### `new_session(sessiontype, peer)`
+发起一个新的会话请求。
+
+**步骤：**
+1. 查找 `sessiontype` 对应的处理器类。
+2. 生成唯一 `sessionid`。
+3. 发送 `{ type: 'new_session', session }` 到服务器。
+4. 创建处理器实例并注册其 `recvdata_handler`。
+5. 返回处理器实例（通常是 `RTCP2PConnect` 实例）。
+
+#### `login()`
+向服务器发送登录请求。
+
+**行为：**
+- 发送 `{ type: 'login' }`。
+- 如果设置了 `heartbeat_period > 0`，启动周期性心跳任务。
+
+#### `logout()`
+发送登出请求 `{ type: 'logout' }`。
+
+#### `send_data(d)`
+将对象序列化为 JSON 并通过 WebSocket 发送。
+
+**附加字段：**
+- `d.msgfrom = this.info`（标识发送者）
+
+#### `socket_send(s)`
+直接发送原始字符串（底层接口，一般不推荐直接使用）。
+
+---
+
+## 3. `bricks.RTCP2PConnect`
+
+WebRTC P2P 连接控制器，处理音视频通话和数据通道通信。
+
+### 构造函数
+```js
+new bricks.RTCP2PConnect(signaling, session, opts)
+```
+
+**参数：**
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `signaling` | `bricks.Signaling` | 信令客户端实例 |
+| `session` | `Object` | 会话元信息 `{ sessionid, sessiontype }` |
+| `opts` | `Object` | 配置项，见下表 |
+
+**`opts` 配置说明：**
+
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `ice_servers` | `Array` | 必需 | ICE 服务器配置（STUN/TURN） |
+| `peer_info` | `Object` | 必需 | 对端用户信息（含 `.id`） |
+| `auto_callaccept` | `Boolean` | `false` | 是否自动接受呼叫 |
+| `media_options` | `Object` | `{ video: true, audio: true }` | 媒体采集选项 |
+| `data_connect` | `Boolean` | `false` | 是否启用数据通道 |
+| `on_pc_connected(peer)` | `Function` | - | 连接建立成功回调 |
+| `on_pc_disconnected(peer)` | `Function` | - | 连接断开回调 |
+| `on_dc_open(dc)` | `Function` | - | 数据通道开启回调 |
+| `on_dc_close(dc)` | `Function` | - | 数据通道关闭回调 |
+| `on_dc_message(dc, data)` | `Function` | - | 收到数据通道消息回调 |
+
+### 属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `id` | `String` | 本地唯一标识（UUID） |
+| `signaling` | `Signaling` | 信令客户端引用 |
+| `session` | `Object` | 当前会话信息 |
+| `requester` | `Boolean` | 是否为主叫方 |
+| `peers` | `Object` | 所有远程连接的 `PeerConnection` 管理对象 |
+| `signal_handlers` | `Object` | 信令消息处理器映射 |
+| `local_stream` | `MediaStream` | 本地摄像头流 |
+| `localVideo` | `VideoBox` | 本地视频预览组件 |
+| `local_screen` | `MediaStream` | 屏幕共享流（可选） |
+
+---
+
+### 核心方法
+
+#### `add_handler(type, f)`
+注册信令消息处理器（如 `'offer'`, `'answer'` 等）。
+
+#### `get_handler(type) → Function`
+获取指定类型的消息处理器。
+
+#### `p2pconnect(peer)`
+尝试与指定对端建立 P2P 连接。
+
+**流程：**
+1. 获取本地媒体流（如果尚未获取）。
+2. 若已存在连接则跳过。
+3. 调用 `createPeerConnection(peer)` 创建新的 `RTCPeerConnection`。
+
+#### `h_sessioncreated(data)`
+当会话创建完成时触发。
+
+**行为：**
+- 自动调用 `p2pconnect`。
+- 若有 `peer_info`，主动发送 `callrequest` 请求呼叫。
+
+#### `h_callrequest(data)`
+收到呼叫请求。
+
+**行为：**
+- 若 `auto_callaccept === true`（或硬编码为 `true`），自动响应：
+  - 建立连接。
+  - 发送 `callaccepted` 消息。
+
+#### `h_callaccepted(data)`
+对方接受呼叫。
+
+**行为：**
+- 创建数据通道（如果启用）。
+- 发送 SDP Offer。
+
+#### `h_offer(data)`
+收到远程 Offer。
+
+**流程：**
+1. 设置 `remoteDescription`。
+2. 创建 Answer。
+3. 设置 `localDescription`。
+4. 发送 Answer 回去。
+5. 如果不是主叫方，再发送一次 Offer（可能存在设计问题，需确认逻辑）。
+
+#### `h_answer(data)`
+收到远程 Answer。
+
+**行为：**
+- 设置 `remoteDescription`。
+
+#### `h_icecandidate(data)`
+收到 ICE 候选地址。
+
+**行为：**
+- 添加到 `RTCPeerConnection` 中。
+
+#### `h_sessionquit(data)`
+收到会话结束通知。
+
+**行为：**
+- 关闭对应 `RTCPeerConnection`。
+
+#### `send_offer(peer, initial = false)`
+创建并发送 SDP Offer。
+
+**参数：**
+- `peer`: 目标用户。
+- `initial`: 是否是首次呼叫（决定角色：`requester` / `responser`）
+
+**流程：**
+1. 创建 Offer。
+2. 设置 `localDescription`。
+3. 通过信令发送 Offer。
+
+#### `send_candidate(peer, event)`
+ICE 候选事件触发时调用，转发候选地址给远端。
+
+> ✅ 使用 `bind(this, peer)` 绑定上下文。
+
+#### `signaling_send(d)`
+封装信令消息，附带当前 `session` 信息后发送。
+
+#### `recvdata_handler(data)`
+统一入口处理所有信令消息：
+- 查找对应处理器并执行。
+- 未处理则输出警告日志。
+
+---
+
+### 连接状态监听
+
+#### `ice_statechange(peer, event)`
+ICE 连接状态变化时的日志输出。
+
+#### `connection_statechange(peer, event)`
+连接状态变化处理：
+- `disconnected`: 触发 `peer_close()` 和 `on_pc_disconnected` 回调。
+- `connected`: 触发 `on_pc_connected` 回调。
+
+---
+
+### 数据通道（DataChannel）
+
+#### `dc_accepted(peer, event)`
+收到远程数据通道请求。
+
+**行为：**
+- 保存 `event.channel`。
+- 调用 `dc_created()` 初始化。
+
+#### `dc_created(peer, dc)`
+初始化数据通道事件监听器：
+- `onmessage` → `datachannel_message`
+- `onopen` → `datachannel_open`
+- `onclose` → `datachannel_close`
+
+#### `datachannel_message(peer, event)`
+收到数据通道消息。
+
+**行为：**
+- 触发 `on_dc_message(dc, event.data)` 回调。
+
+#### `datachannel_open/close(peer)`
+分别在数据通道打开/关闭时触发相应回调。
+
+#### `createDataChannel(peer)`
+主动创建数据通道（用于主叫方）。
+
+---
+
+### 媒体流控制
+
+#### `createPeerConnection(peer)`
+创建并配置 `RTCPeerConnection` 实例。
+
+**关键操作：**
+- 使用传入的 `iceServers`。
+- 添加本地媒体轨道（如有）。
+- 绑定以下事件：
+  - `onicecandidate`
+  - `oniceconnectionstatechange`
+  - `onconnectionstatechange`
+  - `ondatachannel`（注意：拼写错误应为 `ondatachannel`）
+  - `ontrack` → 将远端流绑定到 `VideoBox`
+
+> 🛠️ Bug 提示：`pc.ondatachanel` 应为 `pc.ondatachannel`
+
+#### `changeLocalVideoStream(peer, new_stream)`
+动态更换本地视频流（如切换摄像头或屏幕共享）。
+
+**流程：**
+1. 移除旧的视频 Track。
+2. 添加新流中的视频 Track。
+3. 重新发送 Offer 以更新协商。
+
+#### `getLocalStream()`
+获取本地摄像头和屏幕共享流。
+
+**行为：**
+- 调用 `getUserMedia(media_options)` 获取摄像头流。
+- 调用 `getDisplayMedia({ video: true })` 获取屏幕共享流（音频可选）。
+- 分别赋值给 `this.local_stream` 和 `this.local_screen`。
+- 创建 `localVideo` 并绑定摄像头流用于预览。
+
+> 🔐 权限提示：需要用户授权麦克风和摄像头权限。
+
+---
+
+#### `peer_close(peer)`
+清理与指定对端的所有资源。
+
+**释放内容：**
+- 停止所有接收/发送的媒体 Track。
+- 停止远端视频流。
+- 关闭数据通道和 `RTCPeerConnection`。
+- 删除 `peers` 中的记录。
+- 若无剩余连接，停止本地流并从信令中注销会话处理器。
+
+---
+
+## 使用示例
+
+```js
+// 初始化信令
+var signaling = new bricks.Signaling({
+    signaling_url: 'wss://example.com/signaling',
+    info: { id: 'user123', name: 'Alice' },
+    heartbeat_period: 30,
+    onlogin: function(peers) {
+        console.log('Online users:', peers);
+    }
+});
+
+// 注册 P2P 处理器
+signaling.add_sessionhandler('p2p', bricks.RTCP2PConnect);
+
+// 登录（触发 login）
+signaling.login();
+
+// 发起一个 P2P 会话
+var p2p = signaling.new_session('p2p', { id: 'user456' });
+```
+
+---
+
+## 注意事项与潜在问题
+
+| 问题 | 描述 | 建议修复 |
+|------|------|---------|
+| `ondatachanel` 拼写错误 | 应为 `ondatachannel` | 更正拼写 |
+| `auto_callaccept || true` | 条件恒真，失去意义 | 改为 `this.opts.auto_callaccept === true` |
+| `newStream` 变量名错误 | `changeLocalVideoStream` 中误写为 `newStream` | 改为 `new_stream` |
+| 缺少异常处理 | 多处 `await` 未包裹 `try/catch` | 增加错误捕获 |
+| 心跳任务未清除 | `schedule_once` 可能导致内存泄漏 | 确保正确取消任务 |
+| 未实现自动重连 | `reconnect()` 仅触发回调 | 应加入延迟重试机制 |
+
+---
+
+## 总结
+
+`bricks` 提供了一套完整的 WebRTC 信令与连接管理方案，具有以下特点：
+
+✅ **模块化设计**：分离信令、会话、连接逻辑  
+✅ **扩展性强**：支持多种会话类型  
+✅ **易于集成**：提供 VideoBox 等 UI 组件封装  
+⚠️ **需优化点**：存在若干 bug 与安全限制需处理  
+
+适用于开发音视频会议、直播互动、远程协作等实时通信应用。
\ No newline at end of file
diff --git a/aidocs/running.md b/aidocs/running.md
new file mode 100644
index 0000000..02786d0
--- /dev/null
+++ b/aidocs/running.md
@@ -0,0 +1,198 @@
+# `bricks.Running` 模块技术文档
+
+---
+
+## 概述
+
+`bricks.Running` 是一个用于显示运行中状态（如加载、处理中）的模态窗口组件，通常用于提示用户当前系统正在执行某项任务。它基于 `bricks.BaseModal` 和自定义的 `bricks.BaseRunning` 类构建，提供了一个动态更新的时间计时器和一个可配置的动画图标（默认为 `running.gif`）。
+
+该模块适用于需要可视化反馈长时间操作进度的场景。
+
+---
+
+## 依赖说明
+
+- `bricks.FHBox`：水平布局容器基类。
+- `bricks.BaseModal`：模态窗口基类。
+- `bricks.Icon`：图标显示组件。
+- `bricks.Text`：文本显示组件。
+- `bricks.formatMs()`：格式化毫秒时间的工具函数。
+- `schedule_once()`：定时调度函数，用于周期性执行任务。
+- `bricks_resource()`：资源路径解析函数，用于获取静态资源 URL。
+
+> ⚠️ 注意：以上依赖需在运行环境中提前定义并可用。
+
+---
+
+## 类结构
+
+### 1. `bricks.BaseRunning` 类
+
+继承自 `bricks.FHBox`，用于构建包含图标与运行时间显示的横向控件。
+
+#### 构造函数：`constructor(opts)`
+
+##### 参数
+
+| 参数名 | 类型   | 是否必填 | 描述 |
+|--------|--------|----------|------|
+| `opts.icon` | String | 否 | 图标图片的 URL 路径。若未提供，则使用默认资源路径下的 `running.gif`。 |
+
+##### 功能说明
+
+1. 调用父类构造函数。
+2. 创建一个 `Icon` 组件用于展示运行动画。
+3. 创建一个 `Text` 组件用于实时显示已运行时间。
+4. 初始化起始时间戳（`this.time_start`）。
+5. 将图标和文本控件添加到容器中。
+6. 启动定时任务，每 50ms 更新一次时间显示。
+
+##### 示例代码
+
+```js
+const runner = new bricks.BaseRunning({
+  icon: '/custom/loading.svg'
+});
+```
+
+#### 方法：`show_timepass()`
+
+- **功能**：计算从开始到当前经过的时间，并格式化后更新到 `Text` 控件上。
+- **触发机制**：通过 `schedule_once` 每 50ms 自调用一次，形成持续更新效果。
+- **时间格式**：调用 `bricks.formatMs(t, 1)`，保留一位小数，单位为秒（例如：`3.2s`）。
+
+#### 方法：`stop_timepass()`
+
+- **功能**：停止时间更新任务。
+- **行为**：
+  - 如果存在正在进行的定时任务（`this.showtime_task`），则取消该任务。
+  - 清空任务引用，防止内存泄漏。
+
+---
+
+### 2. `bricks.Running` 类
+
+继承自 `bricks.BaseModal`，封装 `BaseRunning` 成一个自动弹出的模态框。
+
+#### 构造函数：`constructor(opts)`
+
+##### 参数
+
+| 参数名     | 类型   | 是否必填 | 描述 |
+|------------|--------|----------|------|
+| `opts.target` | Element | 否 | 模态框挂载的目标 DOM 元素。默认为 body 或由 BaseModal 决定。 |
+| `opts.icon`   | String  | 否 | 使用的图标路径，将传递给 `BaseRunning`。 |
+
+##### 特性设置
+
+- `auto_open: true`：实例化后自动打开模态框。
+- `archor: 'cc'`：模态框居中对齐（center-center）。
+
+##### 内部逻辑
+
+- 创建 `bricks.BaseRunning` 实例作为内容主体。
+- 将其加入模态框内容区域。
+
+#### 方法：`dismiss()`
+
+- **功能**：关闭模态框前，先停止计时器。
+- **步骤**：
+  1. 调用 `this.w.stop_timepass()` 停止时间更新。
+  2. 调用父类 `BaseModal.dismiss()` 关闭模态框。
+
+> ✅ 提示：此方法确保资源释放和定时器清理。
+
+---
+
+### 3. 工厂注册
+
+```js
+bricks.Factory.register('Running', bricks.Running);
+```
+
+- 将 `Running` 组件注册到 `bricks.Factory` 中，支持通过字符串名称动态创建实例：
+
+```js
+bricks.Factory.create('Running', { icon: 'imgs/custom.gif' });
+```
+
+---
+
+## 使用示例
+
+### 示例 1：基本使用（默认图标）
+
+```js
+new bricks.Running();
+// 弹出居中模态框，显示默认 running.gif 与运行时间
+```
+
+### 示例 2：自定义图标
+
+```js
+new bricks.Running({
+  icon: '/assets/icons/spinner.svg'
+});
+```
+
+### 示例 3：手动关闭
+
+```js
+const runner = new bricks.Running();
+
+// 在某个异步操作完成后关闭
+setTimeout(() => {
+  runner.dismiss(); // 自动停止计时器并关闭模态框
+}, 3000);
+```
+
+---
+
+## 样式与外观
+
+| 组件       | 属性        | 值                     |
+|------------|-------------|------------------------|
+| 文本颜色   | color       | `#222`                 |
+| 文本换行   | wrap        | `false`                |
+| 国际化支持 | i18n        | `false`                |
+| 容器布局   | FHBox       | 水平排列图标与时间文本 |
+| 模态框锚点 | archor      | `'cc'`（居中）         |
+
+> 可通过扩展 CSS 或子类进一步定制样式。
+
+---
+
+## 性能与注意事项
+
+- **刷新频率**：每 50ms 更新一次时间，平衡流畅性与性能。
+- **资源管理**：
+  - 必须调用 `dismiss()` 正确关闭，避免定时器持续运行。
+  - 不手动调用可能导致内存泄漏或界面卡顿。
+- **跨浏览器兼容性**：依赖 `Date.now()` 和 `bind()`，建议配合 polyfill 在旧浏览器中使用。
+
+---
+
+## API 总结
+
+| 类名              | 方法 / 属性           | 类型     | 描述 |
+|-------------------|------------------------|----------|------|
+| `bricks.BaseRunning` | `constructor(opts)`    | 构造函数 | 初始化带图标的运行状态条 |
+|                   | `show_timepass()`      | 方法     | 定时更新运行时间 |
+|                   | `stop_timepass()`      | 方法     | 停止时间更新任务 |
+| `bricks.Running`     | `constructor(opts)`    | 构造函数 | 创建并自动打开模态框 |
+|                   | `dismiss()`            | 方法     | 停止计时并关闭模态框 |
+| `bricks.Factory`     | `.register(type, cls)` | 静态方法 | 注册组件以便工厂创建 |
+
+---
+
+## 版本信息
+
+- **作者**：Bricks Framework Team
+- **版本**：1.0
+- **最后更新**：2025年4月5日
+
+> 更多文档请参考 [Bricks UI 官方文档](https://bricks.example.com/docs)
+
+--- 
+
+📌 **建议用途**：数据加载、文件上传、后台处理等耗时操作的状态提示。
\ No newline at end of file
diff --git a/aidocs/scroll.md b/aidocs/scroll.md
new file mode 100644
index 0000000..085b5eb
--- /dev/null
+++ b/aidocs/scroll.md
@@ -0,0 +1,293 @@
+# Bricks.js 滚动面板组件技术文档
+
+> **项目名称**：`bricks.js`  
+> **模块**：`HScrollPanel` 与 `VScrollPanel`  
+> **功能描述**：提供可监听滚动位置阈值的水平和垂直滚动容器组件。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [依赖说明](#依赖说明)
+- [核心类说明](#核心类说明)
+  - [`low_handle`](#low_handle)
+  - [`bricks.HScrollPanel`](#bricksHScrollPanel)
+  - [`bricks.VScrollPanel`](#bricksVScrollPanel)
+- [事件机制](#事件机制)
+- [工厂注册](#工厂注册)
+- [使用示例](#使用示例)
+- [注意事项](#注意事项)
+
+---
+
+## 概述
+
+`bricks.HScrollPanel` 和 `bricks.VScrollPanel` 是基于 `bricks.HBox` 和 `bricks.VBox` 的扩展类，用于创建具有滚动能力的容器，并在用户滚动接近内容边界时触发自定义事件（如 `min_threshold` 或 `max_threshold`），适用于实现“无限滚动”、“触底加载”等功能。
+
+该组件通过封装原生 DOM 滚动行为，在关键滚动位置触发语义化事件，便于上层逻辑响应。
+
+---
+
+## 依赖说明
+
+本模块依赖以下环境或模块：
+
+- 全局对象 `window.bricks`：框架主命名空间。
+- `bricks.debug()`：调试日志输出函数（仅用于开发期）。
+- `bricks.HBox` / `bricks.VBox`：基础布局容器类。
+- `bricks.Widget.dispatch()`：事件派发方法。
+- `bricks.Factory.register()`：组件工厂注册接口。
+
+---
+
+## 核心类说明
+
+### `low_handle`
+
+#### 功能
+通用滚动阈值判断函数，根据当前滚动位置判断是否到达最小或最大阈值，并触发相应事件。
+
+#### 函数签名
+```js
+function low_handle(widget, dim, last_pos, cur_pos, maxlen, winsize)
+```
+
+#### 参数说明
+
+| 参数名       | 类型     | 描述 |
+|-------------|----------|------|
+| `widget`    | Object   | 触发事件的组件实例（需支持 `.dispatch()` 方法） |
+| `dim`       | String   | 滚动方向标识（`'x'` 或 `'y'`，目前未实际使用但预留） |
+| `last_pos`  | Number   | 上一次记录的滚动位置 |
+| `cur_pos`   | Number   | 当前滚动位置（例如 `scrollLeft` 或 `scrollTop`） |
+| `maxlen`    | Number   | 整体滚动内容长度（`scrollWidth` 或 `scrollHeight`） |
+| `winsize`   | Number   | 可见区域大小（`clientWidth` 或 `clientHeight`） |
+
+#### 行为逻辑
+
+1. 如果当前滚动位置接近右/下边缘（差值小于5像素），则触发 `max_threshold` 事件。
+2. 如果当前滚动位置接近左/上边缘（小于1像素），则触发 `min_threshold` 事件。
+3. 使用 `bricks.debug()` 输出调试信息。
+
+#### 示例调用
+```js
+low_handle(this, 'x', this.last_scrollLeft, e.scrollLeft, e.scrollWidth, e.clientWidth);
+```
+
+---
+
+### bricks.HScrollPanel
+
+水平滚动面板组件，继承自 `bricks.HBox`。
+
+#### 继承关系
+```js
+class HScrollPanel extends bricks.HBox
+```
+
+#### 构造函数
+```js
+constructor(opts)
+```
+
+##### 参数
+| 参数 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `opts.width` | String | 否 | `'100%'` | 宽度设置 |
+| `opts.height` | String | 否 | `'100%'` | 高度设置 |
+| `opts.css` | String | 否 | `''` | 自定义 CSS 类名，自动附加 `scrollpanel` |
+| `opts.overflow` | String | 否 | `'auto'` | 溢出处理方式 |
+| `opts.min_threshold` | Number | 否 | `0.01` | 最小滚动比例阈值（暂未使用） |
+| `opts.max_threshold` | Number | 否 | `0.99` | 最大滚动比例阈值（暂未使用） |
+
+> ⚠️ 注：虽然传入了 `min_threshold` 和 `max_threshold`，但在当前版本中并未参与计算，而是直接使用像素差值判断。
+
+##### 初始化行为
+- 设置默认宽高为 100%。
+- 添加 `scrollpanel` CSS 类。
+- 设置 `overflow: auto` 以启用滚动条。
+- 注册 `scroll` 事件监听器。
+- 记录初始 `scrollLeft` 值。
+
+#### 方法
+
+##### `scroll_handle(event)`
+
+处理滚动事件的核心方法。
+
+###### 参数
+- `event`: DOM 滚动事件对象。
+
+###### 逻辑流程
+1. 确保事件源是当前组件的 DOM 元素。
+2. 检查是否有实际可滚动空间（`scrollWidth > clientWidth + 1`）。
+3. 调用 `low_handle` 判断是否触发边界事件。
+4. 更新 `scroll_info` 状态对象及 `last_scrollLeft`。
+
+###### `scroll_info` 结构
+```js
+{
+  left: number,           // 当前 scrollLeft
+  scroll_width: number,   // scrollWidth
+  client_width: number    // clientWidth
+}
+```
+
+---
+
+### bricks.VScrollPanel
+
+垂直滚动面板组件，继承自 `bricks.VBox`。
+
+#### 继承关系
+```js
+class VScrollPanel extends bricks.VBox
+```
+
+#### 构造函数
+```js
+constructor(opts)
+```
+
+##### 参数
+与 `HScrollPanel` 类似，区别如下：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `min_threshold` | `0.02` | 垂直方向最小阈值 |
+| `max_threshold` | `0.95` | 垂直方向最大阈值 |
+
+> ⚠️ 当前版本中这些阈值仍未被算法使用。
+
+##### 初始化行为
+- 设置默认宽高。
+- 添加 `scrollpanel` 类。
+- 开启 `overflow: auto`。
+- 绑定 `scroll` 事件。
+- 记录初始 `scrollTop`。
+
+#### 方法
+
+##### `scroll_handle(event)`
+
+处理垂直滚动事件。
+
+###### 逻辑流程
+1. 验证事件目标。
+2. 检查是否存在可滚动高度。
+3. 调用 `low_handle` 判断上下边界。
+4. 更新 `scroll_info` 与 `last_scrollTop`。
+
+###### `scroll_info` 结构
+```js
+{
+  top: number,             // scrollTop
+  scroll_height: number,   // scrollHeight
+  client_height: number    // clientHeight
+}
+```
+
+---
+
+## 事件机制
+
+组件会在特定滚动条件下自动派发事件：
+
+| 事件名            | 触发条件 |
+|------------------|---------|
+| `'min_threshold'` | 滚动位置接近顶部或左侧（`< 1px`） |
+| `'max_threshold'` | 滚动位置接近底部或右侧（距离末端 < 5px） |
+
+可通过 `.bind()` 方法监听这些事件：
+
+```js
+panel.bind('min_threshold', function(){
+  console.log('到达顶部/起点');
+});
+```
+
+---
+
+## 工厂注册
+
+为了支持动态创建，两个组件均注册到 `bricks.Factory`：
+
+```js
+bricks.Factory.register('VScrollPanel', bricks.VScrollPanel);
+bricks.Factory.register('HScrollPanel', bricks.HScrollPanel);
+```
+
+这意味着可以通过工厂方式实例化：
+```js
+var vpanel = bricks.Factory.create('VScrollPanel', { ... });
+```
+
+---
+
+## 使用示例
+
+### 创建一个垂直滚动面板并监听边界事件
+
+```js
+var panel = new bricks.VScrollPanel({
+  css: 'my-scroll-container',
+  min_threshold: 0.02,
+  max_threshold: 0.95
+});
+
+panel.bind('min_threshold', function() {
+  console.log('已滚动到顶部，可加载更多...');
+});
+
+panel.bind('max_threshold', function() {
+  console.log('已滚动到底部，加载新数据...');
+});
+
+// 将 panel 添加到父容器中
+parent.append(panel);
+```
+
+### 创建水平滚动面板
+
+```js
+var hpanel = new bricks.HScrollPanel({
+  css: 'horizontal-list'
+});
+
+hpanel.bind('max_threshold', function() {
+  alert('已滑动到最右侧！');
+});
+```
+
+---
+
+## 注意事项
+
+1. **阈值未生效问题**：尽管构造函数接受 `min_threshold` 和 `max_threshold`，但当前 `low_handle` 使用的是固定像素判断（`<1` 和 `<5`），未来建议改为基于比例的动态判断以提升灵活性。
+
+2. **性能优化建议**：
+   - 可添加防抖（debounce）机制避免频繁触发。
+   - 在复杂场景下考虑使用 `requestAnimationFrame` 控制检测频率。
+
+3. **兼容性要求**：
+   - 支持现代浏览器。
+   - 依赖标准 DOM 属性如 `scrollLeft`, `scrollTop`, `scrollWidth`, `clientHeight` 等。
+
+4. **调试模式**：
+   - 使用 `bricks.debug()` 输出日志，上线前应关闭或重定向。
+
+5. **CSS 要求**：
+   - 推荐为 `.scrollpanel` 设置明确的尺寸和 `overflow` 样式，确保滚动正常工作。
+
+---
+
+## 版本信息
+
+- 编写时间：2025年4月
+- 模块版本：v1.0（基础功能版）
+- 维护建议：增加对比例阈值的支持，提升可配置性。
+
+--- 
+
+✅ **文档完**
\ No newline at end of file
diff --git a/aidocs/splitter.md b/aidocs/splitter.md
new file mode 100644
index 0000000..9363750
--- /dev/null
+++ b/aidocs/splitter.md
@@ -0,0 +1,139 @@
+# `bricks.Splitter` 组件技术文档
+
+## 概述
+
+`bricks.Splitter` 是一个基于 `bricks.JsWidget` 的轻量级 UI 组件，用于在页面中创建分隔线（`<hr>` 元素）。它通常用于视觉上分隔不同内容区域，适用于构建模块化布局。
+
+该组件通过 Bricks 框架的工厂模式注册，可通过 `bricks.Factory` 实例化并插入 DOM。
+
+---
+
+## 类定义
+
+```javascript
+bricks.Splitter = class extends bricks.JsWidget
+```
+
+- **继承自**: `bricks.JsWidget`
+- **用途**: 创建水平分隔线（`<hr>`）
+- **注册名称**: `'Splitter'`
+
+---
+
+## 构造函数
+
+### `constructor(ops)`
+
+初始化 `Splitter` 实例。
+
+#### 参数
+
+| 参数名 | 类型   | 说明 |
+|--------|--------|------|
+| `ops`  | Object | 可选配置对象（当前未使用，传递给父类） |
+
+#### 实现细节
+
+```js
+constructor(ops) {
+    super({});
+}
+```
+
+- 调用父类 `bricks.JsWidget` 的构造函数。
+- 当前不依赖任何配置项，传入空对象 `{}`。
+
+---
+
+## 方法
+
+### `create()`
+
+创建并初始化组件的 DOM 结构。
+
+#### 实现
+
+```js
+create() {
+    this.dom_element = this._create('hr');
+}
+```
+
+#### 行为说明
+
+- 使用父类提供的 `_create(tagName)` 工具方法创建一个 `<hr>` 元素。
+- 将生成的 DOM 元素赋值给实例属性 `this.dom_element`，供后续操作使用。
+- `<hr>` 是标准 HTML 水平分隔线元素，语义清晰，样式可通过 CSS 自定义。
+
+---
+
+## 注册与使用
+
+### 注册组件
+
+```js
+bricks.Factory.register('Splitter', bricks.Splitter);
+```
+
+- 将 `Splitter` 类注册到 `bricks.Factory` 中，注册名为 `'Splitter'`。
+- 注册后可通过工厂方法动态创建实例。
+
+---
+
+## 使用示例
+
+### 1. 手动实例化
+
+```js
+const splitter = new bricks.Splitter();
+splitter.create();
+document.body.appendChild(splitter.getElement()); // 假设 getElement() 返回 dom_element
+```
+
+### 2. 通过工厂创建（推荐）
+
+```js
+const splitter = bricks.Factory.create('Splitter');
+splitter.create();
+container.appendChild(splitter.dom_element);
+```
+
+---
+
+## DOM 结构
+
+生成的 DOM 元素：
+
+```html
+<hr>
+```
+
+> 样式可由外部 CSS 控制，例如：
+>
+> ```css
+> hr {
+>   border: 1px solid #ccc;
+>   margin: 16px 0;
+> }
+> ```
+
+---
+
+## 注意事项
+
+- `create()` 方法必须被显式调用以生成 DOM 元素。
+- `dom_element` 属性在 `create()` 调用后才可用。
+- 当前版本不支持自定义标签或复杂配置，如需扩展可继承此类或添加参数支持。
+
+---
+
+## 版本兼容性
+
+- 依赖 `bricks.JsWidget` 基类和 `bricks.Factory` 系统。
+- 需确保 `window.bricks` 已初始化。
+
+---
+
+## 总结
+
+`bricks.Splitter` 是一个简洁、语义化的分隔线组件，适合在组件化界面中快速插入视觉分隔。其设计遵循 Bricks 框架规范，易于集成与扩展。
\ No newline at end of file
diff --git a/aidocs/streaming_audio.md b/aidocs/streaming_audio.md
new file mode 100644
index 0000000..a70a854
--- /dev/null
+++ b/aidocs/streaming_audio.md
@@ -0,0 +1,240 @@
+# `bricks.StreamAudio` 技术文档
+
+> **模块**：`bricks.StreamAudio`  
+> **继承自**：`bricks.VBox`  
+> **用途**：实现基于麦克风音频流的实时语音识别（ASR）前端组件，支持启动/停止录音、音频上传与实时文本反馈。
+
+---
+
+## 概述
+
+`bricks.StreamAudio` 是一个用于浏览器端实时语音处理的 UI 组件。它封装了麦克风采集、语音活动检测（VAD）、音频编码上传以及后端流式响应接收的完整流程，适用于在线语音识别（ASR）场景。
+
+该组件通过按钮控制录音启停，使用 `vad.MicVAD` 进行语音端点检测，并将语音片段以 Base64 编码形式发送到指定服务端 URL，同时接收并显示服务端返回的识别结果文本。
+
+---
+
+## 依赖说明
+
+- `bricks.VBox`：布局容器，垂直排列子控件。
+- `bricks.Button`：用于触发开始/停止操作。
+- `bricks.Filler`：可伸缩填充容器，容纳内容区域。
+- `bricks.Text`：显示识别出的文字内容，支持自动换行。
+- `vad.MicVAD`：语音活动检测模块（假设为外部导入的 VAD 库）。
+- `schedule_once`：延迟执行函数（通常为框架提供的异步调度工具）。
+- `btoa`：JavaScript 内置函数，用于二进制数据转 Base64 字符串。
+- `TextDecoder` / `ReadableStream`：用于解析流式响应体中的 UTF-8 文本。
+
+---
+
+## 构造函数
+
+```js
+constructor(opts)
+```
+
+### 参数
+
+| 参数 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `opts` | Object | 是 | 配置选项对象 |
+
+#### 支持的配置项：
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `height` | String | `'100%'` | 容器高度（会被强制设置） |
+| `name` | String | `'asr_text'` | 组件名称标识 |
+| `url` | String | — | 流式上传的目标服务器地址（必须传入） |
+
+> ⚠️ 注意：`opts.url` 必须在初始化时提供，否则上传无法进行。
+
+### 初始化行为
+
+1. 设置默认高度和名称；
+2. 调用父类构造函数（创建 VBox 布局）；
+3. 创建内部控件：
+   - `this.button`：控制录音启停；
+   - `this.filler`：中间填充区；
+   - `this.text_w`：显示识别结果的文本控件；
+4. 将 `text_w` 添加至 `filler` 中；
+5. 将 `button` 和 `filler` 添加为子组件；
+6. 绑定按钮点击事件到 `toggle_status` 方法。
+
+---
+
+## 核心方法
+
+### `toggle_status()`
+
+切换录音状态（开始 ↔ 停止）
+
+```js
+toggle_status()
+```
+
+根据当前是否正在上传 (`this.upstreaming`) 决定调用 `start()` 或 `stop()`。
+
+---
+
+### `start()`
+
+请求开始录音与上传流程。
+
+```js
+start()
+```
+
+#### 行为：
+- 更新按钮文字为 "stop"；
+- 使用 `schedule_once` 延迟调用 `_start()`，避免同步阻塞 UI。
+
+---
+
+### `async _start()`
+
+实际执行录音启动逻辑的异步方法。
+
+#### 步骤：
+1. 若存在全局 VAD 实例（`bricks.vad`），先停止它（防止冲突）；
+2. 初始化新的 `MicVAD` 实例：
+   - 配置 `onSpeechEnd` 回调：当检测到语音结束时，调用 `handle_audio(audio)` 发送音频；
+3. 启动 VAD 监听；
+4. 记录当前实例为全局唯一活跃 VAD（`bricks.vad = this`）；
+5. 初始化 `UpStreaming` 实例用于上传音频；
+6. 发起连接请求（`.go()`）；
+7. 开始接收服务端响应数据（`recieve_data()`）。
+
+> ✅ 支持并发保护：确保同一时间只有一个录音流激活。
+
+---
+
+### `stop()`
+
+请求停止录音与上传。
+
+```js
+stop()
+```
+
+#### 行为：
+- 更新按钮文字为 "start"；
+- 延迟调用 `_stop()`。
+
+---
+
+### `async _stop()`
+
+实际停止逻辑。
+
+#### 步骤：
+1. 如果有活跃的上传连接（`upstreaming`），调用其 `finish()` 方法通知服务端结束；
+2. 清理 `upstreaming` 引用；
+3. 暂停 VAD 录音；
+4. 解除全局引用（`bricks.vad = null`）。
+
+---
+
+### `async receive_data()`
+
+从服务端流式响应中读取并处理识别结果。
+
+```js
+async receive_data()
+```
+
+#### 工作流程：
+1. 获取响应体的 `reader`（假设 `resp` 已定义且为 `Response.body.getReader()`）；
+2. 使用 `TextDecoder` 解码 UTF-8 数据；
+3. 循环读取每一行文本（模拟逐行解析 SSE 或 NDJSON 流）；
+4. 尝试将每行解析为 JSON；
+   - 成功 → 提取 `d.content` 并更新显示文本；
+   - 失败 → 输出错误日志；
+5. 直到流结束。
+
+> ❗⚠️ 当前代码中 `resp` 变量未定义或作用域错误，应为 `this.resp` 或来自 `this.upstreaming.go()` 的返回值。**此为潜在 bug**。
+
+---
+
+### `handle_audio(audio)`
+
+处理捕获到的音频数据块（通常是 PCM 或 WAV 格式）。
+
+```js
+handle_audio(audio)
+```
+
+#### 功能：
+- 打印调试信息；
+- 将原始音频数据转换为 Base64 字符串；
+- 调用 `this.upstreaming.send(b64audio)` 发送到服务端。
+
+> 🔍 说明：音频格式需与服务端兼容（如小端 PCM、16kHz 单声道等）。
+
+---
+
+## 注册与别名
+
+```js
+bricks.Factory.register('StreamAudio', bricks.StreamAudio);
+bricks.Factory.register('ASRText', bricks.StreamAudio);
+```
+
+允许通过两种标签创建该组件：
+- `<widget type="StreamAudio">`
+- `<widget type="ASRText">`
+
+便于不同项目或历史兼容使用。
+
+---
+
+## 示例用法
+
+```html
+<widget type="ASRText" url="/api/asr/stream"></widget>
+```
+
+或通过 JS 创建：
+
+```js
+const asrWidget = new bricks.StreamAudio({
+  url: '/api/asr/upload',
+  name: 'my_asr'
+});
+document.body.appendChild(asrWidget.dom);
+```
+
+---
+
+## 状态属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `upstreaming` | UpStreaming \| null | 当前上传连接实例 |
+| `vad` | MicVAD \| null | 语音活动检测实例 |
+| `resp_text` | String | 累积的响应文本（暂未使用） |
+| `resp` | Response | 服务端响应对象（可能需要修正作用域） |
+
+---
+
+## 已知问题与改进建议
+
+| 问题 | 描述 | 建议修复 |
+|------|------|----------|
+| `resp` 未定义 | `receive_data()` 中直接使用 `resp.body`，但无声明 | 应从 `this.upstreaming.go()` 返回值获取响应对象 |
+| `reader.readline()` 不存在 | 原生 `ReadableStreamDefaultReader` 不提供 `.readline()` | 需自行实现逐行读取逻辑或引入辅助库 |
+| 错误拼写 | `recieve_data` 函数名拼写错误（应为 `receive`） | 重命名函数及所有调用处 |
+| 异常处理不足 | 接收流过程中缺少中断和重连机制 | 添加网络错误监听与重试逻辑 |
+
+---
+
+## 总结
+
+`bricks.StreamAudio` 是一个功能完整的语音输入前端组件，适合集成于语音助手、实时字幕、语音搜索等系统中。虽然目前存在少量代码瑕疵，但整体结构清晰、职责分明，易于扩展和维护。
+
+建议结合后端 ASR 服务（如 WebSocket + Whisper 或自研引擎）共同部署使用。
+
+--- 
+
+📌 **版本**：1.0  
+📅 **最后更新**：2025-04-05
\ No newline at end of file
diff --git a/aidocs/svg.md b/aidocs/svg.md
new file mode 100644
index 0000000..3cfcbf4
--- /dev/null
+++ b/aidocs/svg.md
@@ -0,0 +1,350 @@
+# `bricks.Svg` 与相关组件技术文档
+
+本文件为 `bricks.Svg` 及其派生类（`StatedSvg` 和 `MultipleStateIcon`）的详细技术说明文档。这些类用于在网页中动态加载、渲染和控制 SVG 图标的行为，支持颜色设置、闪烁动画、URL 动态更新以及状态切换功能。
+
+---
+
+## 模块结构
+
+```js
+var bricks = window.bricks || {};
+```
+
+所有组件均挂载于全局命名空间 `bricks` 下，并通过 `bricks.Factory.register()` 注册为可实例化的 UI 组件。
+
+---
+
+## 1. `bricks.Svg` 类
+
+### 简介
+`bricks.Svg` 是一个继承自 `bricks.VBox` 的类，用于显示并控制单个 SVG 图标的可视化行为。它支持从远程 URL 加载 SVG 内容，动态着色、闪烁动画等特性。
+
+### 继承关系
+```js
+class Svg extends bricks.VBox
+```
+
+---
+
+### 构造函数：`constructor(opts)`
+
+#### 参数
+| 参数 | 类型 | 必需 | 默认值 | 描述 |
+|------|------|------|--------|------|
+| `opts.rate` | Number | 否 | `1` | 缩放比例，影响宽度和高度 |
+| `opts.url` | String | 否 | - | SVG 文件的 URL 地址 |
+| `opts.blink` | Boolean | 否 | `false` | 是否启用闪烁效果 |
+| `opts.color` | String (CSS Color) | 否 | 由 `bricks.app.get_color()` 获取 | SVG 填充颜色 |
+| `opts.blinkcolor` | String (CSS Color) | 否 | 由 `bricks.app.get_bgcolor()` 获取 | 闪烁时的颜色 |
+| `opts.blinktime` | Number | 否 | `0.5` | 闪烁间隔时间（秒） |
+
+> ⚠️ 注意：`opts.cwidth` 和 `opts.cheight` 将被自动设为 `opts.rate`，实现等比缩放。
+
+#### 行为说明
+- 调用父类 `super(opts)` 初始化容器。
+- 若未指定 `color` 或 `blinkcolor`，则使用应用级默认前景/背景色。
+- 若提供了 `url`，调用 `set_url(url)` 加载 SVG 内容。
+- 支持动态尺寸（`dynsize: true`）。
+
+---
+
+### 方法列表
+
+#### `set_url(url)`
+从指定 URL 加载 SVG 内容并插入到 DOM。
+
+##### 参数
+- `url` (String | null)：SVG 文件路径或网址；若为 `null` 或空，则清空内容。
+
+##### 流程
+1. 清除当前内容（若无 `url`）。
+2. 使用 `fetch()` 请求 SVG 文本。
+3. 验证响应是否以 `<svg ` 开头（防止 XSS）。
+4. 存储原始 SVG 文本至 `this.svgText`。
+5. 调用 `set_colored_svg(color)` 渲染带颜色的 SVG。
+6. 如果启用了 `blink`，启动闪烁动画。
+
+> ✅ 安全提示：仅允许标准 `<svg ...>` 标签开头的内容，避免注入风险。
+
+---
+
+#### `set_color(color)`
+设置 SVG 的填充颜色，并立即重新渲染。
+
+##### 参数
+- `color` (String)：合法 CSS 颜色值（如 `"red"`, `"#00ff00"`, `"rgb(255,0,0)"`）
+
+##### 行为
+- 更新 `this.color`
+- 调用 `set_colored_svg(color)`
+
+---
+
+#### `set_blinkcolor(color)`
+设置闪烁状态下的颜色。
+
+##### 参数
+- `color` (String)：目标闪烁颜色
+
+##### 行为
+- 更新 `this.blinkcolor`
+- 自动补全 `blinktime` 为 `0.5`（如果尚未设置）
+
+---
+
+#### `set_colored_svg(color)`
+将模板中的 `{color}` 占位符替换为实际颜色值，并更新 DOM。
+
+##### 参数
+- `color` (String)：要应用的颜色
+
+##### 实现
+```js
+var svgText = bricks.obj_fmtstr({color: color}, this.svgText);
+this.dom_element.innerHTML = svgText;
+```
+
+> 📌 依赖 `bricks.obj_fmtstr` 实现字符串模板替换（类似 `{color}` → `"#ff0000"`）
+
+---
+
+#### `start_blink()`
+启动周期性颜色闪烁动画。
+
+##### 条件
+- 必须设置了 `blinktime > 0`
+- 必须定义了 `blinkcolor`
+
+##### 行为
+- 若当前没有运行任务（`!this.blink_task`），调用 `_blink()` 启动首次切换。
+
+---
+
+#### `_blink()`
+私有方法：执行一次颜色切换，并安排下一次调用。
+
+##### 逻辑
+- 当前颜色是正常色 → 切换为 `blinkcolor`
+- 当前颜色是 `blinkcolor` → 切换回正常 `color`
+- 使用 `schedule_once(fn, delayInSeconds)` 安排下次执行（避免阻塞主线程）
+
+> 🔁 此方法形成递归循环，直到 `end_blink()` 被调用。
+
+---
+
+#### `end_blink()`
+停止闪烁动画。
+
+##### 行为
+- 设置 `this.blink_task = null`，中断 `_blink()` 的递归调度链。
+
+---
+
+#### `set_ancent_color(e)`
+从父元素的计算样式中获取文本颜色，并设置为 SVG 颜色。
+
+##### 应用场景
+适用于希望图标跟随上下文主题色的情况。
+
+##### 实现
+```js
+var pstyle = getComputedStyle(this.parent);
+this.set_color(pstyle.color);
+```
+
+---
+
+## 2. `bricks.StatedSvg` 类
+
+### 简介
+继承自 `bricks.Svg`，支持多个状态（state），每个状态对应不同的 SVG 资源。点击可按顺序切换状态。
+
+### 构造函数：`constructor(opts)`
+
+#### 扩展参数
+| 参数 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `opts.states` | Array<{state: String, url: String}> | 是 | 状态数组，每项包含状态名与对应的 SVG URL |
+| `opts.state` | String | 否 | 初始状态；若不提供，默认取第一个状态 |
+
+#### 初始化行为
+- 设置初始状态 `this.curstate`
+- 调用 `set_state(state)` 加载对应 SVG
+- 绑定 `click` 事件处理器 `trigger`
+
+---
+
+### 方法列表
+
+#### `trigger(event)`
+处理点击事件，顺序切换到下一个状态（循环）。
+
+##### 事件处理
+- `stopPropagation()` 和 `preventDefault()` 阻止冒泡与默认行为
+
+##### 切换逻辑
+- 查找当前状态索引 `i`
+- 下一状态索引：`k = i + 1`，若已达末尾则回到 `0`
+- 调用 `set_state(states[k].state)`
+- 触发 `state_changed` 事件
+
+---
+
+#### `set_state(state)`
+切换到指定状态。
+
+##### 参数
+- `state` (String)：目标状态名称
+
+##### 行为
+- 若已处于该状态，直接返回
+- 遍历 `this.states` 查找匹配项
+- 找到后调用 `set_url(s.url)`
+- 广播 `state_changed` 事件
+- 若未找到匹配项，清除 SVG 内容（`set_url(null)`）
+
+---
+
+## 3. `bricks.MultipleStateIcon` 类
+
+### 简介
+另一种多状态图标实现方式，使用对象字典管理 URL 映射，适合命名清晰的状态切换（如开关、模式选择等）。
+
+### 构造函数：`constructor(opts)`
+
+#### 参数
+| 参数 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `opts.urls` | Object<String, String> | 是 | 状态名到 SVG URL 的映射表，例如 `{on: 'on.svg', off: 'off.svg'}` |
+| `opts.state` | String | 是 | 初始状态键名 |
+
+#### 初始化流程
+- 从 `urls[state]` 提取初始 URL
+- 调用 `super(opts)` 创建基础 SVG
+- 记录 `this.urls` 和当前 `this.state`
+- 绑定 `click` 事件到 `change_state`
+
+---
+
+### 方法列表
+
+#### `change_state(event)`
+点击时切换到下一个状态（按 `Object.keys(urls)` 顺序循环）。
+
+##### 流程
+- 获取所有状态键名数组
+- 查找当前 `state` 的索引
+- 计算下一索引（越界则归零）
+- 调用 `set_state(newState)`
+- 触发 `state_changed` 事件
+
+---
+
+#### `set_state(state)`
+设置当前状态并加载对应 SVG。
+
+##### 参数
+- `state` (String)：目标状态键名
+
+##### 行为
+- 更新 `this.state`
+- 调用 `set_url(this.urls[state])`
+
+---
+
+## 工厂注册
+
+以下三类组件均已向 `bricks.Factory` 注册，可在声明式模板中使用：
+
+```js
+bricks.Factory.register('Svg', bricks.Svg);
+bricks.Factory.register('StatedSvg', bricks.StatedSvg);
+bricks.Factory.register('MultipleStateIcon', bricks.MultipleStateIcon);
+```
+
+这意味着可以通过如下方式创建实例（假设框架支持）：
+```html
+<div data-widget="Svg" data-options='{"url": "icon.svg", "color": "blue"}'></div>
+```
+
+---
+
+## 使用示例
+
+### 示例 1：基础彩色 SVG
+```js
+const icon = new bricks.Svg({
+  url: '/icons/home.svg',
+  color: 'green',
+  blink: true,
+  blinkcolor: 'yellow',
+  blinktime: 0.8
+});
+document.body.appendChild(icon.dom_element);
+```
+
+### 示例 2：三态切换图标（StatedSvg）
+```js
+const light = new bricks.StatedSvg({
+  states: [
+    { state: 'red',   url: '/svg/red.svg' },
+    { state: 'yellow', url: '/svg/yellow.svg' },
+    { state: 'green', url: '/svg/green.svg' }
+  ],
+  state: 'red'
+});
+
+light.on('state_changed', (state) => {
+  console.log('Current state:', state);
+});
+```
+
+### 示例 3：双态图标（MultipleStateIcon）
+```js
+const toggle = new bricks.MultipleStateIcon({
+  urls: {
+    on: '/icons/power-on.svg',
+    off: '/icons/power-off.svg'
+  },
+  state: 'off'
+});
+
+toggle.on('state_changed', s => console.log('Power is now:', s));
+```
+
+---
+
+## 注意事项与最佳实践
+
+| 项目 | 建议 |
+|------|------|
+| **安全性** | 不要加载不可信来源的 SVG，尤其是含 `<script>` 或内联事件的文件 |
+| **性能** | 多次调用 `set_color` 会触发重绘，建议批量操作 |
+| **闪烁控制** | 使用 `start_blink()` / `end_blink()` 显式控制动画生命周期 |
+| **异步加载** | `set_url()` 是异步操作，后续逻辑应放在监听器或 Promise 中处理 |
+| **颜色同步** | 推荐使用 `set_ancent_color()` 实现主题适配 |
+
+---
+
+## 依赖说明
+
+| 依赖项 | 来源 | 用途 |
+|--------|------|------|
+| `bricks.VBox` | 基础布局容器 | 提供 DOM 容器能力 |
+| `bricks.app.get_color()` | 应用配置模块 | 获取默认前景色 |
+| `bricks.app.get_bgcolor()` | 应用配置模块 | 获取默认背景色 |
+| `bricks.obj_fmtstr()` | 字符串工具 | 替换 `{color}` 模板 |
+| `schedule_once(fn, sec)` | 异步调度工具 | 实现非阻塞定时任务 |
+
+---
+
+## 版本信息
+
+- 编写日期：2025年4月5日
+- 框架版本兼容性：BricksJS v1.x+
+- 维护者：前端组件团队
+
+--- 
+
+✅ **文档完成**  
+如有扩展需求，请参考现有接口进行子类化开发。
\ No newline at end of file
diff --git a/aidocs/tab.md b/aidocs/tab.md
new file mode 100644
index 0000000..2bfc8e6
--- /dev/null
+++ b/aidocs/tab.md
@@ -0,0 +1,334 @@
+# `TabPanel` 组件技术文档
+
+> **命名空间**: `bricks.TabPanel`  
+> **继承自**: `bricks.Layout`  
+> **注册名称**: `'TabPanel'`（可通过工厂创建）
+
+---
+
+## 概述
+
+`TabPanel` 是一个可切换内容区域的布局组件，支持多标签页管理。每个标签页可以包含独立的内容组件（如其他 widget），并支持动态加载、缓存和事件通知机制。
+
+标签位置可配置为上下左右四种方向，内容区自动适配布局顺序。
+
+---
+
+## 构造函数
+
+```js
+new bricks.TabPanel(options)
+```
+
+### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `options` | Object | 配置选项对象，继承自 `bricks.Layout` 并扩展以下属性 |
+
+### Options 配置项
+
+```js
+{
+  tab_pos: "top",        // 标签栏位置: 'top', 'bottom', 'left', 'right'
+  tab_long: "100%",      // 标签宽度或高度（CSS 值字符串）
+  items: [               // 标签项数组
+    {
+      name: "tab1",      // 标签唯一标识名（必填）
+      label: "Tab 1",    // 显示文本
+      icon: "",          // 图标类名（可选）
+      removable: false,  // 是否可关闭（显示删除按钮）
+      refresh: false,    // 是否每次点击都重新构建内容
+      content: {         // 内容描述对象，用于构建子 Widget
+        widgettype: "..."// 如: "Text", "Grid" 等
+        // 其他 widget 特定参数
+      }
+    }
+  ],
+  css: ""                // 自定义 CSS 类名（附加到根元素）
+}
+```
+
+> ⚠️ 注意：`content` 可以是标准 widget 描述对象，也可以直接是一个 `bricks.JsWidget` 实例。
+
+---
+
+## 布局结构
+
+根据 `tab_pos` 不同，整体采用 `vbox` 或 `hbox` 布局：
+
+| `tab_pos` | 主轴方向 | 子组件排列顺序 |
+|-----------|----------|----------------|
+| `"top"` / `"bottom"` | 垂直 (`vbox`) | 上/下：标签 → 内容；下/上：内容 → 标签 |
+| `"left"` / `"right"` | 水平 (`hbox`) | 左/右：标签 → 内容；右/左：内容 → 标签 |
+
+- **标签容器**：`this.tab_container`（VBox 容器）
+- **内容容器**：`this.content_container`（Filler 容器，用于动态替换内容）
+
+---
+
+## 样式类（CSS Classes）
+
+组件使用如下 CSS 类进行样式控制：
+
+| 类名 | 作用 |
+|------|------|
+| `.tabpanel` | 根元素样式 |
+| `.tab-button` | 单个标签按钮默认样式 |
+| `.tab-button-active` | 当前激活标签样式 |
+| `.tab-button-hover` | 鼠标悬停时标签样式 |
+| `.tab-content` | 内容区域样式（已通过 `set_css('tabpanel-content')` 设置） |
+| `.vbox`, `.hbox` | 布局方向控制 |
+
+> 开发者可在主题 CSS 中覆盖这些类以自定义外观。
+
+---
+
+## 事件系统
+
+### 1. `switch` 事件（在 TabPanel 上触发）
+
+当标签切换导致内容变更时触发。
+
+- **事件名**: `'switch'`
+- **回调参数**: 被激活的内容 widget 实例
+- **示例**:
+
+```js
+tabpanel.bind('switch', function(widget) {
+  console.log("当前显示内容组件:", widget);
+});
+```
+
+### 2. `active` 事件（在内容 widget 上触发）
+
+当该内容面板被切换为可见状态时，在其自身上触发 `active` 事件。
+
+- **用途**: 用于内容初始化、数据刷新等操作。
+- **示例**:
+
+```js
+contentWidget.bind('active', function() {
+  this.refreshData(); // 自定义刷新逻辑
+});
+```
+
+### 3. Toolbar 内部事件（自动绑定）
+
+- `'command'`: 用户点击标签时触发 → 调用 `show_tabcontent`
+- `'remove'`: 用户关闭标签时触发 → 调用 `tab_removed`
+- `'ready'`: Toolbar 初始化完成后 → 自动显示第一个标签
+
+---
+
+## 方法说明
+
+### `constructor(options)`
+
+初始化 TabPanel 实例，创建标签栏与内容容器，并根据配置设置布局方向。
+
+#### 关键行为：
+- 创建内部 `toolbar` 和 `content_container`
+- 根据 `tab_pos` 设置主轴布局（`vbox` / `hbox`）
+- 调用 `createToolbar()` 构建标签工具栏
+- 最后调用 `show_first_tab()` 显示首个标签页
+
+---
+
+### `show_first_tab()`
+
+手动触发第一个标签页的显示。
+
+```js
+this.show_first_tab();
+```
+
+> 通常由 `'ready'` 事件自动调用。
+
+---
+
+### `createToolbar()`
+
+基于 `options.items` 创建一个 `bricks.Toolbar` 作为标签栏。
+
+#### 行为：
+- 设置 `orientation`：
+  - `top` / `bottom` → `horizontal`
+  - `left` / `right` → `vertical`
+- 绑定事件：
+  - `'command'` → `show_tabcontent`
+  - `'remove'` → `tab_removed`
+  - `'ready'` → `show_first_tab`
+- 添加至 `tab_container`
+
+---
+
+### `async show_tabcontent(event)`
+
+处理标签点击事件，加载并显示对应内容。
+
+#### 流程：
+1. 若点击的是当前标签，忽略重复操作。
+2. 查找匹配的 `item` 配置。
+3. 尝试从缓存 `content_buffer` 获取已有 widget：
+   - 若存在且 `refresh: false`，直接复用。
+4. 否则异步构建新 widget：
+   - 支持直接传入 `bricks.JsWidget` 实例
+   - 或通过 `bricks.widgetBuild()` 解析配置生成
+5. 缓存 widget，调用 `switch_content(w)` 切换显示
+
+> 错误捕获：构建失败会输出 debug 日志。
+
+---
+
+### `switch_content(w)`
+
+切换内容区域为指定 widget。
+
+#### 动作：
+- 清空当前内容容器：`clear_widgets()`
+- 添加新 widget
+- 触发 `switch` 事件（携带 widget 参数）
+- 触发内容 widget 的 `active` 事件
+
+```js
+this.switch_content(widgetInstance);
+```
+
+---
+
+### `add_tab(desc)`
+
+动态添加一个新的标签页。
+
+#### 参数：
+- `desc`: 符合 `items` 结构的对象（必须含 `name`, `label` 等）
+
+#### 行为：
+- 调用 `toolbar.createTool(desc)` 添加按钮
+- 若 `removable === true`，启用关闭功能（需手动实现 UI 支持）
+
+> 示例：
+
+```js
+tabpanel.add_tab({
+  name: 'dynamic',
+  label: '动态标签',
+  content: { widgettype: 'Text', text: '这是动态添加的内容' },
+  removable: true
+});
+```
+
+---
+
+### `tab_removed(event)`
+
+处理标签被移除后的逻辑。
+
+#### 参数：
+- `event.params.name`: 被删除标签的 `name`
+
+#### 行为：
+- 从 `content_buffer` 中清除缓存
+- 如果当前正在显示该标签，则自动切换回第一个标签页
+
+---
+
+## 缓存机制
+
+- 所有已加载的 content widget 缓存在 `this.content_buffer` 对象中（键为 `name`）
+- 默认不重复加载（除非设置 `refresh: true`）
+- 删除标签时自动清理缓存
+
+> 提升性能，避免频繁重建复杂组件。
+
+---
+
+## 使用示例
+
+### 基本用法
+
+```js
+var tabpanel = new bricks.TabPanel({
+  tab_pos: 'top',
+  items: [
+    {
+      name: 'home',
+      label: '首页',
+      content: { widgettype: 'Text', text: '欢迎来到首页' }
+    },
+    {
+      name: 'settings',
+      label: '设置',
+      icon: 'icon-gear',
+      removable: true,
+      content: { widgettype: 'Form', fields: [...] }
+    }
+  ]
+});
+
+document.body.appendChild(tabpanel.get_dom());
+```
+
+### 监听切换事件
+
+```js
+tabpanel.bind('switch', function(activeWidget) {
+  console.log('切换到了:', activeWidget);
+});
+
+// 在内容组件中监听激活事件
+var dashboardWidget = {
+  widgettype: 'Dashboard',
+  init: function() {
+    this.bind('active', function() {
+      this.loadData(); // 仅在显示时加载数据
+    });
+  }
+};
+```
+
+---
+
+## 注册信息
+
+```js
+bricks.Factory.register('TabPanel', bricks.TabPanel);
+```
+
+可通过工厂方式创建：
+
+```js
+bricks.widgetBuild({ widgettype: 'TabPanel', ... }, parent);
+```
+
+---
+
+## 调试信息
+
+- 重复点击相同标签：输出调试日志
+- 内容构建失败：记录错误日志
+- 未匹配的点击事件：提示“无响应”
+
+> 使用 `bricks.debug()` 输出信息（生产环境建议关闭）
+
+---
+
+## 注意事项
+
+1. **name 字段必须唯一**，否则缓存和查找将出错。
+2. **content 必须合法**，确保能被 `widgetBuild` 正确解析。
+3. 若需实时刷新内容，请设置 `refresh: true`。
+4. 移除标签不会销毁 widget，但会清除缓存，防止内存泄漏。
+
+---
+
+## 版本兼容性
+
+- 依赖 `bricks.Layout`, `bricks.Toolbar`, `bricks.Filler`, `bricks.VBox`
+- 需支持 ES6 class 语法
+- 异步加载依赖 Promise 环境
+
+---
+
+✅ **推荐场景**：后台管理系统、多文档界面、配置面板切换等需要标签式导航的 UI 场景。
\ No newline at end of file
diff --git a/aidocs/tabular.md b/aidocs/tabular.md
new file mode 100644
index 0000000..e6f41b4
--- /dev/null
+++ b/aidocs/tabular.md
@@ -0,0 +1,304 @@
+# `bricks.Tabular` 技术文档
+
+```markdown
+# bricks.Tabular 类文档
+
+`bricks.Tabular` 是一个基于 `bricks.DataViewer` 的表格数据展示组件，用于在 Web 界面中以表格形式渲染结构化数据。它支持行选择、复选框状态变更监听、动态内容展开（折叠面板）、字段过滤等功能，适用于需要交互式表格的前端应用场景。
+
+---
+
+## 继承关系
+
+- **继承自**：`bricks.DataViewer`
+- **注册名称**：`Tabular`（通过 `bricks.Factory.register` 注册）
+
+---
+
+## 构造函数
+
+```js
+constructor(opts)
+```
+
+### 参数
+- `opts` (Object) - 配置选项，传递给父类 `DataViewer` 并用于初始化当前实例。
+
+### 说明
+调用父类构造函数后，绑定 `row_check_changed` 事件，触发时执行 `show_check_event_data` 方法（需确保该方法存在或已定义）。
+
+> ⚠️ 注意：`this.show_check_event_data.bind(this)` 表明此方法应在外部实现或混入。
+
+---
+
+## 核心方法
+
+### `async build_other()`
+在数据构建阶段调用，用于初始化编辑字段。
+
+#### 功能
+调用 `get_edit_fields()` 方法，提取可编辑字段列表并存储到 `this.fields` 中。
+
+---
+
+### `async before_data_handle()`
+在处理数据前异步执行的钩子函数。
+
+#### 功能
+1. 调用 `build_header_row()` 创建表头行；
+2. 设置数据偏移量为 1（可能用于跳过表头占位）。
+
+#### 属性设置
+- `this.data_offset = 1`
+
+---
+
+### `async build_header_row()`
+创建并渲染表格的表头行。
+
+#### 实现逻辑
+1. 合并配置项：将 `cheight` 和 `row_options` 扩展为新的 `options`；
+2. 创建 `DataRow` 实例作为表头；
+3. 渲染但不立即插入内容（`render(false)`）；
+4. 添加 CSS 类名 `tabular-header-row`；
+5. 将其添加至滚动容器 `scrollpanel`。
+
+#### 示例代码
+```js
+var dr = new bricks.DataRow(options);
+dr.set_css('tabular-header-row');
+this.scrollpanel.add_widget(dr);
+```
+
+---
+
+### `async build_record_view(record)`
+根据记录数据构建单条记录的视图。
+
+#### 参数
+- `record` (Object) - 数据记录对象。
+
+#### 返回值
+- `Promise<Widget>` - 返回包装后的行控件（VBox 或 DataRow）。
+
+#### 分支逻辑
+| 条件 | 行为 |
+|------|------|
+| `!this.content_view` | 直接返回 `DataRow`，绑定点击事件 |
+| `this.content_view` | 使用 `VBox` 包裹主行和隐藏的内容区，支持展开/折叠 |
+
+##### 内部结构（含 content_view 时）
+- 主显示区域：`row.rec_widget`
+- 折叠内容区域：`row.content_widget`（初始隐藏）
+- 存储原始数据：`row.user_data = record`
+
+##### 事件绑定
+- 点击主行触发 `record_clicked(row, record, event)`
+
+---
+
+### `async record_clicked(row, record, event)`
+处理行点击事件，实现单选高亮与内容展开控制。
+
+#### 参数
+- `row` - 当前行控件（可能是 `DataRow` 或 `VBox`）
+- `record` - 对应的数据记录
+- `event` - 原生事件对象
+
+#### 功能
+1. 取消上一个选中行的高亮样式；
+2. 若启用了 `content_view`，则关闭旧行的内容区；
+3. 切换当前行为选中状态：
+   - 更新 `this.select_row`
+   - 显示高亮样式
+   - 如启用 `content_view`，调用 `toggle_content(true)` 展开内容
+4. 触发 `row_selected` 事件，携带当前记录数据。
+
+---
+
+### `async toggle_content(row, flag)`
+控制某一行的折叠内容区域的显示或隐藏。
+
+#### 参数
+- `row` (VBox) - 包含 `.content_widget` 的行容器
+- `flag` (Boolean) - `true` 展开，`false` 收起
+
+#### 行为
+- `flag === true`:
+  - 显示内容区
+  - 清空现有子控件
+  - 复制 `this.content_view` 描述结构
+  - 应用当前行数据进行模板填充
+  - 异步构建新控件并插入
+- `flag === false`:
+  - 隐藏内容区
+  - 清除所有子控件
+
+> ✅ 支持动态内容渲染，常用于详情展示、表单嵌套等场景。
+
+---
+
+### `get_edit_fields()`
+提取可用于编辑的字段列表，排除指定字段。
+
+#### 参数来源
+- `this.row_options.fields`: 字段定义数组
+- `this.row_options.editexclouded`: 排除字段名数组（拼写疑似错误，应为 `excluded`）
+
+#### 流程
+遍历所有字段，若字段名不在 `editexclouded` 列表中，则加入 `this.fields` 数组。
+
+> ❗ 注意：`editexclouded` 拼写异常，建议检查是否应为 `editExcluded` 或类似命名。
+
+---
+
+### `async build_info(record)`
+构建单条数据行的显示控件（`DataRow`）。
+
+#### 参数
+- `record` (Object | null) - 数据记录；若为空表示构建表头
+
+#### 配置合并
+使用 `bricks.extend` 合并默认高度与行选项。
+
+#### 渲染逻辑
+- 设置 CSS 类名为 `tabular-row`
+- 调用 `dr.render(header)` 控制是否渲染为表头
+- 绑定 `check_changed` 事件 → `record_check_changed`
+
+> 🔤 注释掉的部分涉及工具栏事件代理，目前未启用。
+
+---
+
+### `record_check_changed(event)`
+处理复选框状态变化事件。
+
+#### 行为
+1. 保存最后变更的行到 `this.check_changed_row`
+2. 派发 `row_check_changed` 事件，携带用户数据
+
+#### 派发事件
+- 事件名：`row_check_changed`
+- 参数：`event.params.user_data`
+
+---
+
+### `async renew_record_view(form, row)`
+更新指定行的数据视图（如编辑后刷新显示）。
+
+#### 参数
+- `form` - 表单控件实例，用于获取最新值
+- `row` - 要更新的行控件
+
+#### 步骤
+1. 获取表单数据：`form._getValue()`
+2. 合并到原记录：`bricks.extend(row.user_data, d)`
+3. 调用 `renew(record)` 更新 UI：
+   - 若有 `content_view`：仅更新主显示部分 `rec_widget`
+   - 否则：直接更新整行
+
+---
+
+### `record_event_handle(event_name, record, row, item)`
+通用事件处理器，用于转发来自 `DataRow` 工具栏的操作事件。
+
+#### 参数
+- `event_name` - 事件类型字符串
+- `record` - 当前行数据
+- `row` - 行控件实例
+- `item` - 触发事件的具体元素（如按钮）
+
+#### 行为
+打印日志，并派发对应事件，携带 `record` 数据。
+
+> 📝 日志输出便于调试，生产环境可考虑移除或降级。
+
+---
+
+### `get_hidefields()`
+生成隐藏字段数组，通常用于向后端提交额外参数。
+
+#### 返回值
+- Array<{name, value, uitype}>: 每个字段设置 `uitype: 'hide'`
+
+#### 数据源
+从 `this.data_params` 对象提取键值对，转换为字段格式。
+
+#### 示例输出
+```js
+[
+  { name: "user_id", value: 123, uitype: "hide" },
+  { name: "mode", value: "preview", uitype: "hide" }
+]
+```
+
+---
+
+## 事件系统
+
+| 事件名 | 触发时机 | 携带参数 |
+|-------|---------|--------|
+| `row_check_changed` | 行复选框状态改变 | `record`（用户数据） |
+| `row_selected` | 用户点击某行 | `record`（用户数据） |
+| （转发）任意 `event_name` | 来自 `DataRow.toolbar_w` 的事件 | `record` |
+
+---
+
+## 样式类说明
+
+| CSS 类名 | 用途 |
+|--------|------|
+| `tabular-header-row` | 表头行样式 |
+| `tabular-row` | 普通行样式 |
+| `tabular-row-selected` | 选中行高亮样式 |
+
+---
+
+## 工厂注册
+
+```js
+bricks.Factory.register('Tabular', bricks.Tabular);
+```
+
+允许通过描述符 `{type: 'Tabular', ...}` 动态创建实例。
+
+---
+
+## 使用示例（伪代码）
+
+```js
+var tabular = new bricks.Tabular({
+  cheight: 30,
+  row_options: {
+    fields: [
+      { name: 'name', label: '姓名' },
+      { name: 'age', label: '年龄' }
+    ],
+    editexclouded: ['age'] // age 不参与编辑
+  },
+  content_view: {
+    type: 'Form',
+    items: [
+      { field: 'detail', uitype: 'textarea' }
+    ]
+  }
+});
+
+tabular.bind('row_selected', function(data) {
+  console.log('Selected:', data);
+});
+
+// 加载数据
+tabular.setData(records);
+```
+
+---
+
+## 注意事项
+
+1. **拼写问题**：`editexclouded` 应为 `editExcluded` 或 `excludedFields`，建议修正。
+2. **依赖项**：依赖 `bricks.DataRow`, `bricks.VBox`, `bricks.widgetBuild`, `objcopy`, `bricks.apply_data` 等模块，请确保已加载。
+3. **异步安全**：多数方法标记为 `async`，调用时需使用 `await`。
+4. **事件解绑**：未见销毁生命周期管理，长期运行可能导致内存泄漏。
+
+---
+```
\ No newline at end of file
diff --git a/aidocs/toolbar.md b/aidocs/toolbar.md
new file mode 100644
index 0000000..b5b1ac4
--- /dev/null
+++ b/aidocs/toolbar.md
@@ -0,0 +1,368 @@
+# `bricks.Toolbar` 技术文档
+
+> **模块**：`bricks.Toolbar`  
+> **继承自**：`bricks.Layout`  
+> **用途**：创建可配置的工具栏组件，支持水平/垂直布局、动态工具项生成、点击事件分发及可移除按钮功能。
+
+---
+
+## 概述
+
+`bricks.Toolbar` 是一个基于 `bricks.Layout` 的类，用于构建可视化工具栏。它支持横向或纵向排列的按钮工具项，并提供灵活的配置选项，包括图标、标签、样式、事件绑定等。工具栏中的每个工具项可以触发命令事件，并可选择性地添加“删除”图标以支持动态移除。
+
+该组件使用异步方式创建工具项，确保渲染性能，并通过 `bricks.widgetBuild` 工厂方法统一创建子控件。
+
+---
+
+## 构造函数
+
+### `constructor(options)`
+
+初始化工具栏实例。
+
+#### 参数
+
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `options` | Object | 配置对象，继承自 `bricks.Layout` 并扩展以下属性 |
+
+#### `options` 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `orientation` | String | `'horizontal'` | 布局方向：`'horizontal'` 或 `'vertical'` |
+| `target` | Any | `undefined` | 可选的目标引用，会在事件数据中传递 |
+| `interval` | String 或 Number | `'10px'` | 工具项之间的间隔尺寸（CSS 单位） |
+| `tools` | Array&lt;Object&gt; | `[]` | 工具项描述数组，每项包含图标、名称、标签等信息 |
+| `css` | String | `'toolbar'` | 自定义 CSS 前缀类名 |
+
+#### 示例
+
+```js
+var toolbar = new bricks.Toolbar({
+    orientation: 'horizontal',
+    target: myComponent,
+    interval: '15px',
+    css: 'my-toolbar',
+    tools: [
+        { name: 'save', label: '保存', icon: 'save-icon.svg' },
+        { name: 'delete', label: '删除', icon: 'del-icon.svg', removable: true }
+    ]
+});
+```
+
+#### 实现细节
+
+- 根据 `orientation` 创建 `HScrollPanel`（水平）或 `VScrollPanel`（垂直）作为内部容器。
+- 添加对应 CSS 类：`.htoolbar` 或 `.vtoolbar`。
+- 启用键盘选择：`enable_key_select()`。
+- 使用 `schedule_once` 延迟调用 `createTools()`，避免阻塞主线程。
+
+---
+
+## 成员变量
+
+| 变量 | 类型 | 描述 |
+|------|------|------|
+| `bar` | `bricks.HScrollPanel` / `bricks.VScrollPanel` | 内部滚动面板容器 |
+| `toolList` | Array&lt;Widget&gt; | 存储所有已创建的工具按钮实例 |
+| `clicked_btn` | Widget 或 null | 当前被激活（点击）的按钮 |
+| `preffix_css` | String | CSS 类前缀，用于激活状态样式 |
+
+---
+
+## 方法说明
+
+### `add_interval_box()`
+
+在当前工具栏中插入一个间隔空白区域（`JsWidget`），其大小由 `options.interval` 控制，方向根据 `orientation` 决定。
+
+#### 行为逻辑
+
+- 若为垂直布局 → 设置高度
+- 若为水平布局 → 设置宽度
+
+#### 示例效果
+
+```css
+width: 10px; /* 水平间距 */
+height: 10px; /* 垂直间距 */
+```
+
+> 调用时机：在 `createTools()` 中，两个工具之间自动插入。
+
+---
+
+### `async createTools()`
+
+异步批量创建所有工具项。
+
+#### 流程
+
+1. 遍历 `this.opts.tools`
+2. 调用 `createTool(desc)` 逐个创建
+3. 在非最后一个工具后调用 `add_interval_box()`
+
+#### 注意事项
+
+- 使用 `await` 确保顺序执行（可用于动画或依赖加载）
+- 初始延迟 10ms 执行（通过 `schedule_once(..., 0.01)`）
+
+---
+
+### `async createTool(desc)`
+
+创建单个工具按钮。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `desc` | Object | 工具描述对象，结构如下 |
+
+##### `desc` 结构（工具项配置）
+
+| 属性 | 类型 | 是否必需 | 说明 |
+|------|------|----------|------|
+| `name` | String | ✅ | 工具唯一标识符（用于事件名） |
+| `label` | String | ❌ | 显示文本 |
+| `icon` | String | ❌ | 图标 URL 或 class 名称 |
+| `css` | String | ❌ | 自定义按钮 CSS 类 |
+| `removable` | Boolean | ❌ | 是否显示删除图标，默认 `false` |
+
+#### 返回值
+
+- `{Promise<bricks.Widget>}`：成功时返回按钮控件；失败返回 `undefined`
+
+#### 内部逻辑
+
+1. 构造 `widgetBuild` 所需的选项
+2. 调用 `bricks.widgetBuild(options)` 异步创建按钮
+3. 绑定 `click` 事件到 `do_handle`
+4. 将按钮加入 `toolList` 和 `bar` 容器
+5. 若 `removable == true`，调用 `add_removable(w)`
+6. 触发 `remove` 事件（当用户点击删除图标时）
+
+---
+
+### `remove_item(w, event)`
+
+从工具栏中移除指定工具项。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `w` | Widget | 要移除的按钮控件 |
+| `event` | Event | DOM 事件对象 |
+
+#### 动作
+
+- 从 `bar` 中移除控件
+- 取消选中状态
+- 从 `toolList` 数组中删除
+- 解绑 `click` 事件监听器
+- 分发 `remove` 事件，携带 `tool_opts`
+- 阻止事件冒泡和默认行为
+
+---
+
+### `do_handle(tool, event)`
+
+处理工具按钮点击事件。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `tool` | Widget | 被点击的按钮实例 |
+| `event` | Event | 原始事件对象 |
+
+#### 功能
+
+1. 输出调试日志
+2. 构建事件数据 `d`，合并 `tool.tool_opts` 和可选 `target`
+3. 在 `bar` 上标记该按钮为选中状态
+4. 分发两个事件：
+   - `'command'`：通用命令事件
+   - `[tool.name]`：以工具名命名的特定事件（如 `'save'`, `'delete'`）
+5. 更新激活按钮的 CSS 样式：
+   - 清除上一个激活按钮的样式
+   - 为当前按钮添加 `prefix-css + '-button-active'` 类
+6. 记录当前点击按钮至 `this.clicked_btn`
+
+#### 示例事件数据
+
+```js
+{
+    name: "save",
+    label: "保存",
+    icon: "save-icon.svg",
+    target: myComponent
+}
+```
+
+---
+
+### `add_removable(item)`
+
+为指定工具项添加可删除的 SVG “×” 图标。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `item` | Widget | 支持移除的工具按钮 |
+
+#### 条件判断
+
+- 仅当 `item.tool_opts.removable === true` 时执行
+
+#### 实现步骤
+
+1. 加载 SVG 删除图标（路径来自 `bricks_resource('imgs/delete.svg')`）
+2. 创建 `bricks.Svg` 控件并插入按钮内
+3. 绑定点击事件到 `remove_item`
+4. 输出调试信息
+
+#### 错误处理
+
+- 若 `Svg` 创建失败，输出错误日志
+
+---
+
+### `click(name)`
+
+模拟点击某个工具按钮（通过名称查找）。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `name` | String | 工具项的 `name` 字段 |
+
+#### 行为
+
+遍历 `toolList`，找到匹配 `name` 的按钮并触发其原生 DOM 的 `.click()` 方法，从而激活 `do_handle`。
+
+#### 应用场景
+
+- 外部程序化触发某个命令
+- 快捷键绑定
+
+---
+
+## 事件系统
+
+`Toolbar` 支持以下事件分发：
+
+| 事件名 | 触发条件 | 携带数据 |
+|--------|----------|---------|
+| `command` | 任意工具被点击 | 合并后的工具选项 + target |
+| `[tool.name]` | 特定工具被点击 | 同上 |
+| `remove` | 用户点击删除图标 | 被删除工具的原始 `tool_opts` |
+
+可通过 `bind(event, handler)` 监听这些事件。
+
+#### 示例监听
+
+```js
+toolbar.bind('save', function(data) {
+    console.log('保存操作触发:', data);
+});
+
+toolbar.bind('command', function(cmd) {
+    console.log('收到命令:', cmd.name);
+});
+```
+
+---
+
+## 样式类说明
+
+| CSS 类 | 作用 |
+|-------|------|
+| `.htoolbar` | 水平工具栏根元素样式 |
+| `.vtoolbar` | 垂直工具栏根元素样式 |
+| `.toolbar-button-active` | 激活按钮状态（默认前缀） |
+| `[custom]-button-active` | 自定义前缀激活样式（由 `css` 选项控制） |
+
+> 推荐在主题 CSS 中定义相关样式。
+
+---
+
+## 注册与工厂模式
+
+```js
+bricks.Factory.register('Toolbar', bricks.Toolbar);
+```
+
+允许通过字符串标识符创建实例：
+
+```js
+bricks.create({
+    widgettype: 'Toolbar',
+    options: { ... }
+});
+```
+
+---
+
+## 使用示例
+
+### 完整 HTML 示例
+
+```html
+<div id="toolbar-container"></div>
+
+<script>
+var toolbar = new bricks.Toolbar({
+    container: document.getElementById('toolbar-container'),
+    orientation: 'horizontal',
+    interval: '12px',
+    target: app.mainView,
+    css: 'app-toolbar',
+    tools: [
+        { name: 'new', label: '新建', icon: 'icons/new.svg' },
+        { name: 'open', label: '打开', icon: 'icons/open.svg' },
+        { name: 'save', label: '保存', icon: 'icons/save.svg', removable: true }
+    ]
+});
+
+// 监听事件
+toolbar.bind('save', function(data) {
+    console.log('正在保存...', data.target);
+});
+
+// 程序触发
+setTimeout(() => toolbar.click('new'), 1000);
+</script>
+```
+
+---
+
+## 调试信息
+
+启用 `bricks.debug` 后，会输出以下信息：
+
+- 工具构建失败
+- 删除图标加载结果
+- 点击事件详情
+- 可移除功能启用状态
+
+建议开发阶段开启调试模式。
+
+---
+
+## 总结
+
+`bricks.Toolbar` 提供了一个现代化、可扩展的工具栏解决方案，具备以下特性：
+
+✅ 支持横竖布局  
+✅ 动态工具生成  
+✅ 事件驱动架构  
+✅ 支持可删除项  
+✅ 样式可定制  
+✅ 兼容工厂创建模式  
+
+适合集成于富客户端应用、编辑器、IDE 工具条等场景。
\ No newline at end of file
diff --git a/aidocs/tree.md b/aidocs/tree.md
new file mode 100644
index 0000000..3558242
--- /dev/null
+++ b/aidocs/tree.md
@@ -0,0 +1,356 @@
+# `bricks.Tree` 与 `bricks.TreeNode` 技术文档
+
+> **版本：1.0**  
+> **模块：Tree 组件（树形结构 UI 控件）**
+
+---
+
+## 概述
+
+`bricks.Tree` 是一个基于 `bricks.js` 框架的可交互树形组件，支持异步数据加载、节点展开/折叠、选中/勾选操作、动态增删改节点等功能。它适用于展示层级数据结构（如文件系统、组织架构等），并提供完整的前端交互逻辑和后端通信能力。
+
+该组件由两个核心类构成：
+
+- `bricks.Tree`: 树的容器类，继承自 `bricks.VScrollPanel`，负责管理整体布局、数据获取、工具栏及事件分发。
+- `bricks.TreeNode`: 单个树节点类，继承自 `bricks.VBox`，表示树中的一个节点，包含图标、文本、子节点区域等元素。
+
+---
+
+## 类定义
+
+### `bricks.TreeNode`
+
+#### 继承关系
+```js
+class TreeNode extends bricks.VBox
+```
+
+#### 构造函数
+```js
+constructor(tree, parent_node, data)
+```
+
+##### 参数说明：
+| 参数         | 类型     | 描述 |
+|--------------|----------|------|
+| `tree`       | `bricks.Tree` | 当前节点所属的树实例 |
+| `parent_node`| `bricks.TreeNode` 或 `null` | 父节点引用；根节点为 `null` |
+| `data`       | `Object` | 节点绑定的数据对象 |
+
+##### 初始化行为：
+- 设置默认选项（宽度 100%，高度自适应）
+- 初始化节点状态字段（是否为叶子节点、是否已加载子节点等）
+- 设置图标 URL（根据类型或默认配置）
+- 创建主内容行（`HBox`），绑定点击事件
+- 异步创建节点内容（图标、复选框、文本或自定义视图）
+- 若非叶子节点，则创建子节点容器（`VBox`），初始隐藏
+
+---
+
+### `bricks.Tree`
+
+#### 继承关系
+```js
+class Tree extends bricks.VScrollPanel
+```
+
+#### 构造函数
+```js
+constructor(options)
+```
+
+##### 参数说明（`options` 对象）：
+| 属性名 | 类型 | 必需 | 默认值 | 描述 |
+|--------|------|------|--------|------|
+| `row_height` | String | 否 | `'35px'` | 每行节点的高度 |
+| `idField` | String | 是 | - | 数据中标识唯一 ID 的字段名 |
+| `textField` | String | 是 | - | 显示节点文本的字段名 |
+| `is_leafField` | String | 否 | `'is_leaf'` | 判断是否为叶子节点的字段名 |
+| `typeField` | String | 否 | - | 区分节点类型的字段名（用于图标定制） |
+| `data` | Array | 否 | - | 静态数据源（本地 JSON 数组） |
+| `dataurl` | String | 否 | - | 动态获取子节点数据的 API 地址 |
+| `method` | String | 否 | `'GET'` | 请求数据时使用的 HTTP 方法 |
+| `params` | Object | 否 | `{}` | 发送请求时携带的额外参数 |
+| `node_view` | WidgetDesc \| Function | 否 | - | 自定义节点渲染模板（可通过 `widgetBuild` 解析） |
+| `checkField` | String | 否 | - | 控制节点勾选状态的字段名 |
+| `editable` | Object | 否 | - | 编辑功能配置（增删改 URL 和字段） |
+| `node_typeicons` | Object | 否 | 内置默认图标 | 不同类型节点的图标配置 |
+| `multitype_tree` | Boolean | 否 | `false` | 是否启用多类型树显示 |
+
+##### 初始化行为：
+- 创建滚动面板
+- 构建标题与描述（预留接口）
+- 创建工具栏（如果启用了编辑模式或自定义工具）
+- 初始化容器用于放置节点
+- 如果有 `dataurl`，则异步加载根节点数据；否则使用本地 `data` 构建树
+
+---
+
+## 主要方法
+
+### `bricks.TreeNode` 方法
+
+| 方法名 | 说明 |
+|-------|------|
+| `getValue()` | 返回当前节点及其所有子节点的完整数据结构（递归） |
+| `get_id()` | 获取节点 ID（通过 `idField` 字段） |
+| `selected(flg)` | 设置节点选中状态样式 |
+| `toggleExpandCollapse(event)` | 切换展开/收起状态（异步） |
+| `expand()` | 展开节点（若未加载过子节点且存在 `dataurl`，会先请求数据） |
+| `collapse()` | 收起节点 |
+| `create_triple()` | 创建带状态切换功能的 SVG 图标（展开/收起） |
+| `change_node_type()` | 根据是否为叶子节点设置图标行为 |
+| `create_node_content(widget)` | 渲染节点内部内容（图标、复选框、文本或自定义组件） |
+| `update_content()` | 更新节点显示内容（主要用于刷新文本或视图） |
+| `setup_icon_urls()` | 根据节点类型配置图标路径（支持按 type 定制） |
+
+---
+
+### `bricks.Tree` 方法
+
+| 方法名 | 说明 |
+|-------|------|
+| `getValue()` | 获取整棵树的数据结构（含所有子节点） |
+| `get_id()` | 获取树根节点 ID |
+| `create_toolbar()` | 创建顶部工具栏（添加、编辑、删除按钮及其他命令） |
+| `toolbar_command(event)` | 工具栏命令处理器（响应用户操作） |
+| `add_new_node()` | 打开模态窗添加新节点 |
+| `new_node_inputed(event)` | 处理新增节点表单提交 |
+| `append_new_subnode(node, data)` | 在指定节点下追加子节点 |
+| `build_subnode(node, data)` | 构建并插入一个 `TreeNode` 实例 |
+| `delete_node()` | 删除当前选中节点（弹出确认框） |
+| `delete_node_conformed(event)` | 确认删除后的处理逻辑 |
+| `delete_subnode(node, subnode)` | 从父节点中移除子节点（更新数据与 DOM） |
+| `update_node()` | 编辑当前选中节点（打开表单） |
+| `update_node_inputed(event)` | 处理编辑表单提交 |
+| `update_node_data(node, data)` | 应用新数据到节点，并刷新 UI |
+| `get_children_data(node)` | 通过 AJAX 获取某节点的子节点数据 |
+| `create_node_children(node, data)` | 使用给定数据批量创建子节点 |
+| `node_click_handle(node, event)` | 节点点击处理（控制选中状态切换） |
+| `node_selected(node, flag)` | 分发节点选中事件 |
+| `node_checked(node, event)` | 处理节点勾选状态变化，维护 `checked_data` 列表 |
+
+---
+
+## 事件机制
+
+### 内部触发事件（通过 `dispatch` 分发）
+
+| 事件名 | 触发时机 | 参数说明 |
+|--------|---------|----------|
+| `node_selected` | 节点被选中或取消选中 | 包含节点原始数据 + `selected: true/false` |
+| `check_changed` | 节点勾选状态改变 | 节点数据对象 |
+| `[command]` | 工具栏执行命令（如 `add`, `delete`） | 命令参数 + 元数据（referer、title 等） |
+
+> 示例监听方式：
+```js
+tree.bind('node_selected', function(e){
+    console.log('Selected node:', e.params);
+});
+```
+
+---
+
+## 图标与资源管理
+
+### 图标策略
+
+- 支持三种状态图标：
+  - `open`: 展开状态图标
+  - `close`: 收起状态图标
+  - `leaf`: 叶子节点图标
+
+- 图标来源优先级：
+  1. `node_typeicons[type]` —— 按节点类型指定
+  2. 回退到 `default_type`
+  3. 使用内置默认图标集
+
+```js
+this.node_typeicons = {
+    folder: {
+        open: '/static/imgs/open-folder.svg',
+        close: '/static/imgs/close-folder.svg',
+        leaf: '/static/imgs/file.svg'
+    },
+    default_type: 'folder'
+}
+```
+
+- 使用 `bricks_resource(path)` 解析静态资源路径。
+
+---
+
+## 编辑功能（EditableTree）
+
+当配置 `editable` 选项时，启用增删改功能：
+
+```js
+editable: {
+    fields: [ /* 表单字段定义 */ ],
+    add_url: '/api/node/add',
+    delete_url: '/api/node/delete',
+    update_url: '/api/node/update'
+}
+```
+
+### 功能流程
+
+| 操作 | 流程 |
+|------|------|
+| 添加节点 | 弹出 `ModalForm` → 提交 → 调用 `add_url` → 成功后插入新节点 |
+| 删除节点 | 确认对话框 → 调用 `delete_url` → 移除 DOM 与数据 |
+| 修改节点 | 加载当前数据至表单 → 提交 → 调用 `update_url` → 局部刷新 UI |
+
+> 注意：表单数据自动附加 `idField` 和 `parentField`（如有父节点）
+
+---
+
+## 数据结构要求
+
+### 节点数据格式示例
+
+```json
+{
+    "id": "n1",
+    "name": "项目A",
+    "type": "project",
+    "is_leaf": false,
+    "children": [
+        {
+            "id": "n11",
+            "name": "子任务1",
+            "is_leaf": true
+        }
+    ]
+}
+```
+
+### 关键字段映射（可配置）
+
+| 配置项 | 默认字段 |
+|--------|----------|
+| `idField` | `id` |
+| `textField` | `name`（需在 `opts.textField` 中指定） |
+| `is_leafField` | `is_leaf` |
+| `typeField` | （可选）`type` |
+
+---
+
+## 使用示例
+
+### 静态树（本地数据）
+
+```js
+var tree = new bricks.Tree({
+    idField: 'id',
+    textField: 'name',
+    is_leafField: 'is_leaf',
+    data: [
+        { id: '1', name: '父节点', is_leaf: false, children: [
+            { id: '2', name: '子节点', is_leaf: true }
+        ]}
+    ]
+});
+tree.open();
+```
+
+### 动态树（远程加载）
+
+```js
+var tree = new bricks.Tree({
+    idField: 'id',
+    textField: 'label',
+    dataurl: '/api/tree/nodes',
+    params: { app: 'doc' },
+    row_height: '40px'
+});
+document.body.appendChild(tree.dom_element);
+```
+
+### 可编辑树
+
+```js
+var editableTree = new bricks.Tree({
+    idField: 'id',
+    textField: 'title',
+    dataurl: '/api/tree',
+    editable: {
+        fields: [
+            { name: 'title', label: '标题', type: 'text' },
+            { name: 'type', label: '类型', type: 'select', options: [...] }
+        ],
+        add_url: '/api/node/add',
+        delete_url: '/api/node/delete',
+        update_url: '/api/node/update'
+    }
+});
+```
+
+---
+
+## 异步加载机制
+
+- 使用 `schedule_once(fn, delay)` 延迟执行以避免阻塞主线程
+- 子节点数据仅在首次展开时请求一次（`children_loaded` 标志位控制）
+- 支持无限层级嵌套
+
+---
+
+## 工具栏（Toolbar）
+
+自动构建于树上方（如果启用了编辑或自定义工具）：
+
+- 支持图标+文字按钮
+- 可扩展自定义命令
+- 命令可通过以下方式注入数据：
+  - `selected_data: true` → 传入选中节点数据
+  - `checked_data: true` → 传入所有勾选节点
+  - 否则传入上下文数据（选中 > 勾选 > params）
+
+---
+
+## 注册组件
+
+```js
+bricks.Factory.register('Tree', bricks.Tree);
+bricks.Factory.register('EditableTree', bricks.EditableTree); // 假设存在别名
+```
+
+允许通过描述符动态创建：
+```js
+bricks.widgetBuild({ widgettype: 'Tree', ...options }, parent);
+```
+
+---
+
+## 已知限制与注意事项
+
+1. **性能优化建议**：对于超大数据集（>1000 节点），建议启用虚拟滚动或懒加载优化。
+2. **复选框过滤问题**：`checked_data` 过滤逻辑目前仅比较 `id`，应确保唯一性。
+3. **FormData 处理**：对 `FormData` 类型做了特殊处理（`.append()`），兼容性强。
+4. **图标路径错误排查**：注意 `bricks_resource()` 是否正确解析路径。
+5. **循环引用风险**：`TreeNode` 持有 `tree` 和 `parent_node` 引用，注意内存释放。
+
+---
+
+## 附录：依赖函数说明
+
+| 函数 | 来源 | 用途 |
+|------|------|------|
+| `bricks.extend(a, b)` | utils | 对象浅合并 |
+| `bricks.uuid()` | utils | 生成唯一 ID |
+| `bricks_resource(path)` | global | 解析资源路径 |
+| `schedule_once(fn, delay)` | scheduler | 延迟执行函数 |
+| `formdata2object(fd)` | utils | 将 FormData 转为普通对象 |
+| `new bricks.HttpJson()` | net | 封装 JSON 请求 |
+
+---
+
+## 版本历史
+
+- v1.0：初版发布，支持基本树形结构、异步加载、编辑操作、事件系统
+
+---
+
+> 文档维护者：Bricks Framework Team  
+> 最后更新：2025年4月5日
\ No newline at end of file
diff --git a/aidocs/tree_choose.md b/aidocs/tree_choose.md
new file mode 100644
index 0000000..01f9db0
--- /dev/null
+++ b/aidocs/tree_choose.md
@@ -0,0 +1,106 @@
+# `bricks.TreeChoose` 技术文档
+
+## 概述
+
+`bricks.TreeChoose` 是 `bricks` 框架中的一个类，用于实现树形结构的选择组件。该组件继承自 `bricks.VBox`，提供了一个可扩展的容器结构，适用于展示和选择层级数据（如目录树、组织架构等）。
+
+---
+
+## 命名空间
+
+```javascript
+var bricks = window.bricks || {};
+```
+
+确保 `bricks` 命名空间在全局作用域中存在，若不存在则初始化为空对象，以避免命名冲突或引用错误。
+
+---
+
+## 类定义
+
+```javascript
+bricks.TreeChoose = class extends bricks.VBox {
+    /* 
+    {
+    }
+    */
+    constructor(opts) {
+        super(opts);
+    }
+}
+```
+
+### 继承关系
+
+- **父类**: `bricks.VBox`
+- **说明**: `VBox` 通常表示一个垂直布局容器，`TreeChoose` 在其基础上扩展功能，用于构建树形选择界面。
+
+---
+
+## 构造函数
+
+### `constructor(opts)`
+
+初始化 `TreeChoose` 实例。
+
+#### 参数
+
+| 参数名 | 类型   | 说明 |
+|--------|--------|------|
+| `opts` | Object | 配置选项对象，将传递给父类构造函数。目前未定义特定选项，继承自 `VBox` 的配置。 |
+
+#### 实现
+
+```js
+constructor(opts) {
+    super(opts); // 调用父类构造函数
+}
+```
+
+- 调用 `super(opts)` 以完成父类 `VBox` 的初始化。
+- 当前版本未添加额外初始化逻辑，保留扩展空间。
+
+---
+
+## 当前功能状态
+
+- ✅ 继承自 `VBox`，具备基本容器能力。
+- 🚫 尚未实现树形渲染、节点选择、展开/收起等核心功能。
+- 📌 注释块 `{}` 可能为未来配置项预留结构。
+
+---
+
+## 使用示例（待扩展）
+
+```js
+const treeChoose = new bricks.TreeChoose({
+    // 后续可支持的配置项（示例）
+    // data: [...],          // 树形数据
+    // multiple: false,      // 是否多选
+    // onSelect: function(node) { ... }
+});
+document.body.appendChild(treeChoose.getElement());
+```
+
+> ⚠️ 当前类为空壳结构，需进一步开发以支持实际功能。
+
+---
+
+## 未来开发建议
+
+1. 添加树形数据绑定方法（如 `setData(data)`）。
+2. 实现节点点击事件与选择状态管理。
+3. 支持异步加载子节点（懒加载）。
+4. 提供样式定制与事件回调机制。
+
+---
+
+## 版本信息
+
+- 初始版本：0.1.0（基础类结构）
+- 所属框架：`bricks.js`
+- 最后更新：2025年4月5日
+
+--- 
+
+> 📝 注：本文档基于当前代码结构生成，实际功能需后续完善。
\ No newline at end of file
diff --git a/aidocs/uitype.md b/aidocs/uitype.md
new file mode 100644
index 0000000..5cc4755
--- /dev/null
+++ b/aidocs/uitype.md
@@ -0,0 +1,274 @@
+# `bricks.uiViewers` 模块技术文档
+
+---
+
+## 概述
+
+`bricks.uiViewers` 是一个基于工厂模式的 UI 视图构建系统，用于根据不同的数据类型（`uitype`）动态创建对应的 UI 组件。该模块通过注册和获取视图构建器函数，实现对多种数据类型的可视化展示。
+
+它适用于需要根据配置动态渲染字段内容的场景（如表单预览、数据展示等），支持字符串、图标、代码、密码、隐藏字段、音频等多种类型。
+
+---
+
+## 命名空间结构
+
+```javascript
+var bricks = window.bricks || {};
+bricks.uiViewers = {};
+```
+
+- `bricks`：全局命名空间对象，防止污染全局作用域。
+- `bricks.uiViewers`：存储所有已注册的视图构建器函数的对象，键为 `uitype`，值为构建函数。
+
+---
+
+## 核心方法
+
+### `bricks.add_ViewBuilder(uitype, handler)`
+
+注册一个新的视图构建器。
+
+#### 参数
+
+| 参数      | 类型     | 描述 |
+|-----------|----------|------|
+| `uitype`  | `String` | 数据/字段类型的标识符（如 `'str'`, `'icon'` 等）。 |
+| `handler` | `Function` | 构建 UI 组件的处理函数，接收 `opts` 配置对象并返回一个组件实例。 |
+
+#### 示例
+
+```js
+bricks.add_ViewBuilder('str', function(opts){
+    return new bricks.Text({ otext: opts.value });
+});
+```
+
+> 此方法将指定的 `handler` 存入 `bricks.uiViewers` 对象中，以 `uitype` 为键。
+
+---
+
+### `bricks.get_ViewBuilder(uitype)`
+
+获取已注册的视图构建器函数。
+
+#### 参数
+
+| 参数      | 类型     | 描述 |
+|-----------|----------|------|
+| `uitype`  | `String` | 要获取的构建器对应的类型名称。 |
+
+#### 返回值
+
+- `{Function|null}`：如果存在对应 `uitype` 的构建器，则返回该函数；否则返回 `undefined`。
+
+#### 示例
+
+```js
+var builder = bricks.get_ViewBuilder('str');
+if (builder) {
+    var widget = builder({ value: 'Hello' });
+}
+```
+
+---
+
+## 内置视图构建器
+
+以下为默认注册的几种常见类型及其行为说明。
+
+---
+
+### `'str'` - 字符串显示
+
+使用 `bricks.Text` 组件显示普通文本，并支持国际化（i18n）。
+
+#### 构建逻辑
+
+```js
+bricks.add_ViewBuilder('str', function(opts){
+    var options = bricks.extend({}, opts);
+    options.otext = opts.value;
+    options.i18n = true;
+    return new bricks.Text(options);
+});
+```
+
+#### 说明
+
+- 复制原始 `opts` 配置。
+- 设置显示文本为 `opts.value`。
+- 启用国际化支持。
+
+---
+
+### `'icon'` - 图标显示
+
+显示一个图标组件，通常基于 URL 或类名。
+
+#### 构建逻辑
+
+```js
+bricks.add_ViewBuilder('icon', function(opts){
+    var options = bricks.extend({}, opts);
+    options.url = opts.value;
+    return new bricks.Icon(options);
+});
+```
+
+#### 说明
+
+- 将 `value` 字段作为图标的资源地址（URL）传入 `bricks.Icon`。
+
+---
+
+### `'code'` - 代码/富文本显示
+
+用于显示可配置字段的文本内容，优先从 `user_data` 中提取。
+
+#### 构建逻辑
+
+```js
+bricks.add_ViewBuilder('code', function(opts){
+    var textField = opts.textField || 'text';
+    var valueField = opts.name;
+    var txt;
+    if (opts.user_data) {
+        txt = opts.user_data[textField] || opts.user_data[valueField] || '';
+    } else {
+        txt = opts.value || '';
+    }
+    var options = bricks.extend({}, opts);
+    options.otext = txt;
+    options.i18n = true;
+    return new bricks.Text(options);
+});
+```
+
+#### 说明
+
+- 支持从 `user_data` 对象中读取内容，优先级：`textField > valueField > fallback ''`。
+- 若无 `user_data`，则使用 `opts.value`。
+- 使用 `bricks.Text` 显示结果，并启用 i18n。
+
+---
+
+### `'password'` - 密码占位显示
+
+安全地显示密码字段，仅展示掩码。
+
+#### 构建逻辑
+
+```js
+bricks.add_ViewBuilder('password', function(opts){
+    var options = bricks.extend({}, opts);
+    options.otext = '******';
+    options.i18n = true;
+    return new bricks.Text(options);
+});
+```
+
+#### 说明
+
+- 实际值不暴露，统一显示为六个星号 `******`。
+- 仍使用 `bricks.Text` 组件进行渲染。
+
+---
+
+### `'hide'` - 隐藏字段
+
+创建一个空的占位组件，不显示任何内容。
+
+#### 构建逻辑
+
+```js
+bricks.add_ViewBuilder('hide', function(opts){
+    return new bricks.JsWidget({});
+});
+```
+
+#### 说明
+
+- 返回一个空的 `JsWidget` 实例，用于占位但不可见。
+- 常用于逻辑控制或后台数据绑定。
+
+---
+
+### `'audio'` - 音频播放器
+
+嵌入一个音频播放控件，支持自动播放开关。
+
+#### 构建逻辑
+
+```js
+bricks.add_ViewBuilder('audio', function(opts){
+    var options = bricks.extend({}, opts);
+    var url = options.value;
+    return new bricks.AudioPlayer({ url: url, autoplay: false });
+});
+```
+
+#### 说明
+
+- 从 `opts.value` 提取音频文件 URL。
+- 创建 `AudioPlayer` 实例，默认禁用自动播放。
+
+---
+
+## 扩展性与自定义
+
+开发者可通过 `bricks.add_ViewBuilder` 方法扩展新的字段类型支持。
+
+### 自定义示例
+
+```js
+bricks.add_ViewBuilder('image', function(opts) {
+    return new bricks.Image({
+        src: opts.value,
+        alt: opts.label || 'Image'
+    });
+});
+```
+
+> 只需确保 `uitype` 不冲突即可无缝集成。
+
+---
+
+## 依赖说明
+
+本模块依赖以下 `bricks` 子模块：
+
+| 模块             | 用途 |
+|------------------|------|
+| `bricks.extend`   | 对象浅拷贝工具函数（类似 jQuery.extend）。 |
+| `bricks.Text`     | 文本显示组件。 |
+| `bricks.Icon`     | 图标显示组件。 |
+| `bricks.JsWidget` | 基础 UI 容器组件。 |
+| `bricks.AudioPlayer` | 音频播放组件。 |
+
+> 确保这些组件在运行时已加载。
+
+---
+
+## 使用示例
+
+```js
+// 获取构建器
+var builder = bricks.get_ViewBuilder('str');
+// 创建组件
+var textWidget = builder({ value: 'Hello World' });
+// 插入 DOM
+textWidget.renderTo(document.body);
+```
+
+---
+
+## 总结
+
+| 特性         | 说明 |
+|--------------|------|
+| **设计模式** | 工厂模式 + 注册中心 |
+| **可扩展性** | 高，支持动态添加新类型 |
+| **安全性**   | 敏感信息（如密码）做了脱敏处理 |
+| **灵活性**   | 支持从不同数据源提取内容（如 `user_data`） |
+
+此模块是构建动态 UI 展示层的核心组件之一，适合用于低代码平台、表单引擎、CMS 内容预览等场景。
\ No newline at end of file
diff --git a/aidocs/uitypesdef.md b/aidocs/uitypesdef.md
new file mode 100644
index 0000000..74d30f6
--- /dev/null
+++ b/aidocs/uitypesdef.md
@@ -0,0 +1,428 @@
+# Bricks UI 类型定义与构建系统技术文档
+
+本文档描述了 `bricks.UiTypesDef` 类及其相关工厂函数和构建器，用于实现基于 `uitype` 的视图（View）和输入控件（Input）的动态创建机制。该系统支持灵活扩展不同数据类型的 UI 表现形式。
+
+---
+
+## 目录
+
+- [1. 概述](#1-概述)
+- [2. 核心类：UiTypesDef](#2-核心类uitypesdef)
+  - [构造函数](#constructoropts)
+  - [set(uitype, viewBuilder, inputBuilder)](#setuitype-viewbuilder-inputbuilder)
+  - [get(uitype)](#getuitype)
+  - [getViewBuilder(uitype)](#getviewbuilderviewbuilder)
+  - [getInputBuilder(uitype)](#getinputbuilderinputbuilder)
+  - [setViewBuilder(uitype, Builder)](#setviewbuilderviewbuilder)
+  - [setInputBuilder(uitype, Builder)](#setinputbuilderinputbuilder)
+- [3. 工厂函数](#3-工厂函数)
+  - [bricks.viewFactory(desc, rec)](#bricksviewfactorydesc-rec)
+  - [bricks.inputFactory(desc, rec)](#bricksinputfactorydesc-rec)
+- [4. 内置构建器](#4-内置构建器)
+  - [通用辅助函数](#通用辅助函数)
+    - [buildText(text, halign)](#buildtexttext-halign)
+  - [字符串类型 (`str`)](#字符串类型-str)
+    - [strViewBuilder](#strviewbuilder)
+    - [strInputBuilder](#strinputbuilder)
+  - [密码类型 (`password`)](#密码类型-password)
+    - [passwordViewBuilder](#passwordviewbuilder)
+    - [passwordInputBuilder](#passwordinputbuilder)
+  - [整数类型 (`int`)](#整数类型-int)
+    - [intViewBuilder](#intviewbuilder)
+  - [浮点数类型 (`float`)](#浮点数类型-float)
+    - [floatViewBuilder](#floatviewbuilder)
+  - [编码/字典类型 (`code`)](#编码字典类型-code)
+    - [codeViewBuilder](#codeviewbuilder)
+
+---
+
+## 1. 概述
+
+`bricks.UiTypesDef` 是一个管理 **UI 类型映射** 的核心类，它将特定的数据类型（如 `str`, `int`, `password` 等）与对应的 **视图构建器（viewBuilder）** 和 **输入构建器（inputBuilder）** 关联起来。
+
+通过注册不同的构建器函数，可以实现对字段描述（`desc`）和记录数据（`rec`）自动生成 UI 控件的能力。
+
+系统提供两个主要工厂函数：
+- `viewFactory`: 创建只读文本显示控件
+- `inputFactory`: 创建可编辑输入控件
+
+默认情况下，所有未匹配的类型会尝试回退到 `'str'` 类型处理。
+
+---
+
+## 2. 核心类：`UiTypesDef`
+
+```javascript
+bricks.UiTypesDef = class {
+  constructor(opts)
+}
+```
+
+### `constructor(opts)`
+
+初始化 `UiTypesDef` 实例。
+
+#### 参数
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `opts` | Object | 可选配置对象（当前未使用） |
+
+#### 属性
+- `this.uitypes`: 存储每种 `uitype` 对应的构建器对象，结构如下：
+  ```js
+  {
+    uitype: {
+      viewBuilder: Function,
+      inputBuilder: Function
+    }
+  }
+  ```
+
+---
+
+### `set(uitype, viewBuilder, inputBuilder)`
+
+注册一个 UI 类型的视图和输入构建器。
+
+#### 参数
+| 参数名 | 类型 | 必需 | 说明 |
+|--------|------|------|------|
+| `uitype` | String | 是 | UI 类型名称，例如 `'str'`, `'int'` |
+| `viewBuilder` | Function | 否 | 用于生成只读视图的函数 |
+| `inputBuilder` | Function | 否 | 用于生成可编辑输入控件的函数 |
+
+> 若对应 `uitype` 尚未存在，则自动创建容器对象。
+
+---
+
+### `get(uitype)`
+
+获取指定 `uitype` 的 `[viewBuilder, inputBuilder]` 数组。
+
+#### 返回值
+- 成功时返回 `[viewBuilder, inputBuilder]`
+- 失败时返回 `(null, null)`（注意：原代码有误，实际返回 `[null, null]` 更合理）
+
+#### 示例
+```js
+const [viewFn, inputFn] = bricks.uitypesdef.get('str');
+```
+
+---
+
+### `getViewBuilder(uitype)`
+
+获取指定类型的视图构建器函数。
+
+#### 参数
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `uitype` | String | 要查询的 UI 类型 |
+
+#### 返回值
+- `Function`：视图构建器
+- 若不存在则返回 `undefined`
+
+> ⚠️ 注意：原代码中若找不到返回的是 `this.uitypes[uitype].viewBuilder`，即可能为 `undefined`，但注释写成返回 `Null`，可能是笔误。
+
+---
+
+### `getInputBuilder(uitype)`
+
+获取指定类型的输入构建器函数。
+
+#### 参数
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `uitype` | String | 要查询的 UI 类型 |
+
+#### 返回值
+- `Function`：输入构建器
+- 若不存在则返回 `Null`（注意：JavaScript 中应为 `null`，而非首字母大写的 `Null` —— 原代码此处可能存在错误）
+
+---
+
+### `setViewBuilder(uitype, Builder)`
+
+仅设置某个 `uitype` 的视图构建器。
+
+#### 参数
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `uitype` | String | UI 类型 |
+| `Builder` | Function | 视图构建函数 |
+
+> 如果该 `uitype` 无条目，则先初始化空对象。
+
+---
+
+### `setInputBuilder(uitype, Builder)`
+
+仅设置某个 `uitype` 的输入构建器。
+
+#### 参数
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `uitype` | String | UI 类型 |
+| `Builder` | Function | 输入构建函数 |
+
+> 同上，若不存在则先创建占位对象。
+
+---
+
+## 3. 工厂函数
+
+### `bricks.viewFactory(desc, rec)`
+
+根据字段描述和数据记录生成对应的只读视图组件。
+
+#### 参数
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `desc` | Object | 字段描述对象，必须包含 `.uitype` 和 `.name` |
+| `rec` | Object | 数据记录对象，字段值从中提取 |
+
+#### 流程
+1. 提取 `desc.uitype`
+2. 查找注册的 `viewBuilder`
+3. 若未找到，尝试使用 `'str'` 类型作为默认 fallback
+4. 若仍无 builder，返回 `Null`（⚠️ 应为 `null`）
+5. 调用 builder 生成控件并返回
+
+#### 返回值
+- UI 控件实例（如 `Text` 组件），或 `null`
+
+#### 示例
+```js
+const widget = bricks.viewFactory({ uitype: 'int', name: 'age' }, { age: 25 });
+// 返回右对齐的文本 "25"
+```
+
+---
+
+### `bricks.inputFactory(desc, rec)`
+
+生成可编辑的输入控件。
+
+#### 参数
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `desc` | Object | 字段描述 |
+| `rec` | Object | 当前数据记录 |
+
+#### 流程
+1. 获取 `uitype`
+2. 查找 `inputBuilder`，失败则 fallback 到 `'str'`
+3. 若无 builder，返回 `Null`（⚠️ 同样应为 `null`）
+4. 调用 builder 并返回结果
+
+#### 返回值
+- 输入控件实例（如 `UiStr`, `UiPassword`），或 `null`
+
+#### 示例
+```js
+const input = bricks.inputFactory({ uitype: 'password', name: 'pwd' }, {});
+// 返回 UiPassword 控件
+```
+
+---
+
+## 4. 内置构建器
+
+### 通用辅助函数
+
+#### `buildText(text, halign)`
+
+创建一个标准化的文本控件。
+
+##### 参数
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `text` | String | 显示文本内容 |
+| `halign` | String | 水平对齐方式，仅支持 `'left'` 或 `'right'`，其他值默认为 `'left'` |
+
+##### 返回值
+- `Text` 实例，具有以下属性：
+  ```js
+  {
+    text: text || '',
+    overflow: 'hidden',
+    wrap: true,
+    halign: 'left' // 固定左对齐？注意这里硬编码了 left！
+  }
+  ```
+> ❗ 注意：尽管参数允许传入 `halign`，但在构造 `Text` 时却固定写死为 `'left'`，这可能导致逻辑不一致！
+
+建议修正为：
+```js
+halign: halign // 而非 'left'
+```
+
+---
+
+### 字符串类型 (`str`)
+
+#### `strViewBuilder(desc, rec)`
+
+生成字符串类型的只读视图。
+
+##### 实现
+- 从 `rec[desc.name]` 取值
+- 使用 `buildText(v, 'left')` 显示，左对齐
+
+##### 注册
+```js
+bricks.uitypesdef.setViewBuilder('str', strViewBuilder);
+```
+
+#### `strInputBuilder(desc, rec)`
+
+生成字符串输入控件。
+
+##### 实现
+- 设置 `desc.value` 为当前字段值（⚠️ 原代码中 `desc[value]` 存在语法错误！应为 `desc.value`）
+- 返回 `new UiStr(desc)`
+
+##### 错误提示
+```js
+desc[value] = v; // ❌ 语法错误！value 未定义
+```
+✅ 正确应为：
+```js
+desc.value = v;
+```
+
+##### 注册
+```js
+bricks.uitypesdef.setInputBuilder('str', strInputBuilder);
+```
+
+---
+
+### 密码类型 (`password`)
+
+#### `passwordViewBuilder(desc, rec)`
+
+显示掩码文本 `******`，保护隐私。
+
+##### 实现
+- 忽略真实值，始终显示六个星号
+- 调用 `buildText('******')`
+
+##### 注册
+```js
+bricks.uitypesdef.setViewBuilder('password', passwordViewBuilder);
+```
+
+#### `passwordInputBuilder(desc, rec)`
+
+生成密码输入框。
+
+##### 实现
+- 直接返回 `new UiPassword(desc)`
+- 不依赖 `rec` 值（由组件自身管理）
+
+##### 注册
+```js
+bricks.uitypesdef.setInputBuilder('password', passwordInputBuilder);
+```
+
+---
+
+### 整数类型 (`int`)
+
+#### `intViewBuilder(desc, rec)`
+
+将数值转为字符串，并右对齐显示。
+
+##### 实现
+- `v = rec[desc.name] + ''`（强制转字符串）
+- 调用 `buildText(v, 'right')`
+
+##### 注册
+```js
+bricks.uitypesdef.setViewBuilder('int', intViewBuilder);
+```
+
+---
+
+### 浮点数类型 (`float`)
+
+#### `floatViewBuilder(desc, rec)`
+
+格式化浮点数，保留小数位后显示。
+
+##### 参数扩展
+- `desc.dec_len`：指定小数位数，默认为 `2`
+
+##### 实现
+```js
+v = rec[desc.name];
+v = v.toFixed(desc.dec_len || 2); // 格式化
+v = v + ''; // 转字符串
+return buildText(v, 'right'); // 右对齐
+```
+
+##### 注册
+```js
+bricks.uitypesdef.setViewBuilder('float', floatViewBuilder);
+```
+
+---
+
+### 编码/字典类型 (`code`)
+
+适用于下拉选择、字典项等场景的只读显示。
+
+#### `codeViewBuilder(desc, rec)`
+
+##### 参数处理
+- 克隆 `desc` 为 `opts`
+- 若存在 `uiparams`，将其属性合并到 `opts`
+- 支持两个字段名优先级：
+  1. `textFeild`（拼写疑似错误，应为 `textField`）
+  2. `valueField`
+
+##### 查找逻辑
+```js
+v = rec[desc.textFeild || 'text']
+if (!v) v = rec[desc.valueField || 'value']
+```
+
+> ⚠️ 注意：`textFeild` 很可能是拼写错误，应为 `textField`
+
+##### 显示
+- 左对齐文本控件
+
+##### 注册
+```js
+bricks.uitypesdef.setViewBuilder('code', codeViewBuilder);
+```
+
+---
+
+## 已知问题与改进建议
+
+| 问题 | 说明 | 建议修复 |
+|------|------|---------|
+| `desc[value] = v` | JavaScript 语法错误 | 改为 `desc.value = v` |
+| `return Null` | 非法标识符（应为 `null`） | 所有 `Null` → `null` |
+| `halign:'left'` in `buildText` | 忽略参数，始终左对齐 | 改为 `halign: halign` |
+| `textFeild` 拼写错误 | 可能导致字段无法正确识别 | 改为 `textField` |
+| 默认 fallback 使用 `'str'` | 合理但需确保 `'str'` 已注册 | 初始化时必须保证基础类型存在 |
+
+---
+
+## 总结
+
+本模块实现了基于 `uitype` 的 UI 构建策略模式，具备良好的扩展性：
+
+- 新增类型只需调用 `setViewBuilder` / `setInputBuilder`
+- 工厂函数统一接口调用
+- 支持 fallback 机制增强健壮性
+
+适合用于表单渲染、列表展示等需要动态 UI 生成的场景。
+
+--- 
+
+> ✅ **维护建议**：增加类型校验、异常捕获、单元测试以提升稳定性。
\ No newline at end of file
diff --git a/aidocs/utils.md b/aidocs/utils.md
new file mode 100644
index 0000000..6e1f2d7
--- /dev/null
+++ b/aidocs/utils.md
@@ -0,0 +1,787 @@
+# Bricks.js 技术文档
+
+> **Bricks.js** 是一个轻量级的前端工具库，提供了一系列实用函数和类，用于处理 DOM 操作、事件监听、数据转换、网络请求、媒体流播放等常见任务。它支持响应式设计、动态组件构建，并兼容移动端与桌面端环境。
+
+---
+
+## 目录
+
+- [初始化](#初始化)
+- [核心配置](#核心配置)
+- [时间与格式化](#时间与格式化)
+- [DOM 与观察者](#dom-与观察者)
+- [URL 与资源管理](#url-与资源管理)
+- [数据处理与类型判断](#数据处理与类型判断)
+- [颜色解析](#颜色解析)
+- [异步与流式响应](#异步与流式响应)
+- [Blob 与 Base64 转换](#blob-与-base64-转换)
+- [表单与对象操作](#表单与对象操作)
+- [调试系统](#调试系统)
+- [设备检测](#设备检测)
+- [UI 定位与布局](#ui-定位与布局)
+- [扩展方法（Array）](#扩展方法array)
+- [Cookie 操作](#cookie-操作)
+- [高度同步](#高度同步)
+- [深拷贝与对象操作](#深拷贝与对象操作)
+- [媒体流播放](#媒体流播放)
+- [模板渲染与组件构建](#模板渲染与组件构建)
+- [可观察对象 Observable](#可观察对象-observable)
+- [队列结构 Queue](#队列结构-queue)
+- [DOM 创建工具](#dom-创建工具)
+
+---
+
+## 初始化
+
+```js
+var bricks = window.bricks || {};
+```
+
+确保 `bricks` 全局命名空间存在，避免覆盖已有变量。
+
+---
+
+## 核心配置
+
+### `bricks.bug`
+- **类型**: `boolean | string`
+- **默认值**: `false`
+- **说明**: 控制是否开启调试模式。
+  - `false`: 不输出任何调试信息。
+  - `true`: 在控制台打印调用栈和参数。
+  - `'server'`: 将日志发送到服务器 `/debug` 接口。
+
+---
+
+## 时间与格式化
+
+### `bricks.timeDiff(startTime)`
+计算当前时间与指定时间之间的差值，并格式化为 `HH:mm:ss.SSS` 字符串。
+
+#### 参数
+| 参数名     | 类型             | 说明                     |
+|----------|------------------|------------------------|
+| startTime | `Date \| number` | 开始时间（毫秒或 Date 对象） |
+
+#### 返回值
+- **类型**: `string`
+- **格式**: `"HH:mm:ss.SSS"`
+
+#### 示例
+```js
+const start = new Date() - 3661000; // 1小时1分钟1秒前
+console.log(bricks.timeDiff(start)); // "01:01:01.000"
+```
+
+---
+
+## DOM 与观察者
+
+### `bricks.resize_observer`
+使用 `ResizeObserver` 监听元素尺寸变化。
+
+#### 功能
+- 自动触发绑定了 `bricks_widget` 的组件的 `element_resize` 事件。
+- 传递 `contentRect` 作为事件参数。
+
+#### 使用方式
+```js
+widget.dom_element.bricks_widget = widget;
+bricks.resize_observer.observe(widget.dom_element);
+```
+
+---
+
+### `bricks.dom_on_off_observer`
+使用 `MutationObserver` 监听 DOM 添加/移除事件。
+
+#### 触发事件
+| 事件名    | 触发条件           |
+|---------|------------------|
+| `domon`  | 元素被添加到 DOM     |
+| `domoff` | 元素从 DOM 移除（包括后代）|
+
+#### 配置
+- 监听 `document.body`
+- 启用 `childList` 和 `subtree`，深度遍历所有子节点。
+
+#### 注意事项
+- 只处理元素节点（Node Type === 1）
+- 支持嵌套组件自动解绑
+
+---
+
+## URL 与资源管理
+
+### `addParamsToUrl(url, params, widget)`
+向 URL 添加查询参数，支持相对路径。
+
+#### 参数
+| 参数     | 类型     | 说明                   |
+|--------|--------|----------------------|
+| url    | string | 原始 URL（相对或绝对）       |
+| params | object | 要添加的键值对参数          |
+| widget | any    | （未使用，保留字段）        |
+
+#### 返回值
+- **类型**: `string`
+- 包含新参数的完整 URL
+
+#### 示例
+```js
+addParamsToUrl('/api/data', { id: 123 }); 
+// => "http://current-domain/api/data?id=123"
+```
+
+---
+
+### `bricks.absurl(url, widget)`
+生成绝对 URL，基于 `widget.baseURI` 或 `bricks.Body.baseURI`。
+
+#### 规则
+- 若 URL 已是 `http://` 或 `https://`，直接返回。
+- 若以 `/` 开头，则基于根路径拼接。
+- 否则基于当前脚本所在目录补全。
+
+#### 示例
+```js
+bricks.absurl('style.css'); // => "https://example.com/path/to/style.css"
+```
+
+---
+
+### `bricks.path`
+- **类型**: `string`
+- 当前执行脚本所在的目录路径（末尾不带 `/`）
+
+由 `currentScriptPath()` 函数设置。
+
+---
+
+### `bricks_resource(name)`
+根据 `bricks.path` 生成资源路径。
+
+#### 示例
+```js
+bricks_resource('img/logo.png');
+// => "https://example.com/scripts/img/logo.png"
+```
+
+---
+
+## 数据处理与类型判断
+
+### `isString(value)`
+判断是否为字符串类型。
+
+#### 返回值
+- `true` if `typeof value === 'string'` or `value instanceof String`
+
+---
+
+### `formdata2object(formdata)`
+将 `FormData` 转换为普通 JavaScript 对象。
+
+#### 示例
+```js
+const fd = new FormData();
+fd.append('name', 'Alice');
+formdata2object(fd); // { name: "Alice" }
+```
+
+---
+
+### `inputdata2dic(data)`
+提取 `FormData` 所有字段，对 `prompt` 字段进行特殊字符转义。
+
+#### 特性
+- 自动调用 `bricks.escapeSpecialChars(x)` 处理 `prompt` 字段
+- 异常捕获：若失败则原样返回输入数据
+
+---
+
+### `bricks.map(data_source, mapping, need_others)`
+按映射规则重命名对象属性。
+
+#### 参数
+| 参数         | 说明                             |
+|------------|----------------------------------|
+| data_source | 源对象                            |
+| mapping     | 键映射表 `{旧名: 新名}`            |
+| need_others | 是否保留未映射的原始字段              |
+
+#### 示例
+```js
+bricks.map({ a: 1, b: 2 }, { a: 'x' }, true); 
+// => { x: 1, b: 2 }
+```
+
+---
+
+### `bricks.delete_null_values(obj)`
+删除对象中所有值为 `null` 的属性。
+
+#### 示例
+```js
+bricks.delete_null_values({ a: null, b: 2 }); // { b: 2 }
+```
+
+---
+
+### `bricks.is_empty(obj)`
+判断对象是否为空（`null` 或 `{}`）。
+
+#### 示例
+```js
+bricks.is_empty(null);      // true
+bricks.is_empty({});        // true
+bricks.is_empty({ a: 1 });  // false
+```
+
+---
+
+## 颜色解析
+
+### `parseRGB(colorStr)`
+解析 `rgb(r, g, b)` 格式的颜色字符串。
+
+#### 成功返回
+```js
+{ r: 255, g: 100, b: 50 }
+```
+
+#### 失败返回
+- `null`
+
+---
+
+### `parseRGBA(colorStr)`
+解析 `rgba(r, g, b, a?)` 格式颜色字符串，`a` 可选，默认 `1`。
+
+#### 示例
+```js
+parseRGBA('rgba(255, 0, 0, 0.8)'); // { r: 255, g: 0, b: 0, a: 0.8 }
+parseRGBA('rgb(255, 0, 0)');       // { r: 255, g: 0, b: 0, a: 1 }
+```
+
+---
+
+## 异步与流式响应
+
+### `streamResponseJson(response, onJson)`
+逐行解析 NDJSON 流式响应并回调处理每个 JSON 对象。
+
+#### 参数
+| 参数       | 类型       | 说明                       |
+|----------|----------|--------------------------|
+| response | Response | fetch 返回的响应对象           |
+| onJson   | Function | 每解析一行有效的 JSON 后调用该函数 |
+
+#### 特性
+- 支持 UTF-8 解码
+- 缓冲未完成的行至下次读取
+- 自动忽略空行和解析错误
+
+#### 示例
+```js
+fetch('/stream').then(res => streamResponseJson(res, json => {
+  console.log('Received:', json);
+}));
+```
+
+---
+
+## Blob 与 Base64 转换
+
+### `base64_to_url(base64, mimeType)`
+将 Base64 字符串转换为 Blob URL。
+
+#### 参数
+| 参数        | 默认值         | 说明               |
+|-----------|--------------|------------------|
+| base64    | required     | Base64 编码的数据    |
+| mimeType  | `"audio/wav"` | MIME 类型           |
+
+#### 返回值
+- `string`: `blob:` URL
+
+#### 示例
+```js
+const audioUrl = base64_to_url(base64Data);
+new Audio(audioUrl).play();
+```
+
+---
+
+### `blobToBase64(blob)`
+异步将 Blob 转换为 Data URL（包含 Base64 编码）。
+
+#### 返回值
+- `Promise<string>`: 如 `"data:audio/wav;base64,..."`
+
+#### 示例
+```js
+const dataUrl = await blobToBase64(blob);
+```
+
+---
+
+## 表单与对象操作
+
+### `bricks.formdata_copy(fd)`
+克隆 `FormData` 实例。
+
+#### 返回值
+- 新的 `FormData` 实例，内容与原实例一致。
+
+---
+
+### `objcopy(obj)`
+通过 `JSON.stringify + JSON.parse` 实现浅层深拷贝。
+
+#### 局限性
+- 不支持函数、undefined、Symbol、循环引用
+
+---
+
+### `objget(obj, key, defval)`
+安全获取对象属性，类似 Python 的 `.get()` 方法。
+
+#### 示例
+```js
+objget({ a: 1 }, 'b', 'default'); // "default"
+```
+
+---
+
+### `bricks.obj_fmtstr(obj, fmt)`
+模板字符串替换，支持 `${key}` 和 `${key:}` 语法。
+
+#### 支持语法
+| 语法           | 效果                          |
+|--------------|-----------------------------|
+| `${name}`     | 替换为 `obj.name`              |
+| `${name:}`    | 替换为 `"name:value"` 形式       |
+| `${name=}`    | 同上（兼容旧写法）                 |
+| 不存在的 key    | 替换为空字符串                    |
+
+#### 示例
+```js
+bricks.obj_fmtstr({ name: "Tom" }, "Hello ${name}!"); 
+// => "Hello Tom!"
+```
+
+---
+
+## 调试系统
+
+### `bricks.debug(...args)`
+统一调试输出接口。
+
+#### 行为逻辑
+- 如果 `bricks.bug === false` → 无输出
+- 如果 `bricks.bug === true` → 输出到控制台 + 调用栈
+- 如果 `bricks.bug === 'server'` → 延迟 0.1s 发送到 `/debug` 接口
+
+#### 示例
+```js
+bricks.bug = true;
+bricks.debug('Test message', { x: 1 });
+// [调用位置] Test message {x: 1}
+```
+
+---
+
+### `bricks.serverdebug(message)`
+将消息 POST 到 `/debug` 接口（需配合后端接收）。
+
+#### 内部使用
+- 通过 `bricks.HttpJson().post()` 发送
+- 仅当 `bricks.bug === 'server'` 时启用
+
+---
+
+## 设备检测
+
+### `bricks.is_mobile()`
+判断是否为移动设备。
+
+#### 判断依据
+1. UserAgent 包含常见移动设备关键词
+2. 存在触摸事件支持（`ontouchstart`, `maxTouchPoints`）
+3. 屏幕尺寸 ≤ 768×1024
+
+#### 返回值
+- `true` if mobile device
+
+---
+
+## UI 定位与布局
+
+### `archor_at(archor)`
+计算锚点坐标百分比。
+
+#### 支持锚点
+| 值  | 含义         |
+|-----|------------|
+| tl  | 左上         |
+| tc  | 顶部居中      |
+| tr  | 右上         |
+| cl  | 中左         |
+| cc  | 居中（默认）   |
+| cr  | 中右         |
+| bl  | 左下         |
+| bc  | 底部居中      |
+| br  | 右下         |
+
+#### 返回值
+```js
+{ x: "50%", y: "50%", left: "50%", top: "50%" }
+```
+
+---
+
+### `archorize(ele, archor)`
+将元素定位到指定锚点，并应用 CSS transform 居中。
+
+#### 效果
+- 设置 `position: absolute`
+- 设置 `top`, `left`
+- 使用 `transform: translateY(-y) translateX(-x)` 精确居中
+
+#### 示例
+```js
+archorize(menuEl, 'tr'); // 右上角弹出菜单
+```
+
+---
+
+### `bricks.relocate_by_eventpos(event, widget)`
+根据鼠标点击位置智能调整组件位置，避免溢出视口。
+
+#### 策略
+- X轴：左侧或右侧展开（避开边缘）
+- Y轴：上方或下方展开
+- 留出 `bricks.app.charsize` 边距
+
+#### 应用场景
+- 上下文菜单
+- 提示框浮动定位
+
+---
+
+## 扩展方法（Array）
+
+### `Array.prototype.insert(index, ...items)`
+在指定索引插入多个元素。
+
+#### 示例
+```js
+[1, 2].insert(1, 'a', 'b'); // [1, 'a', 'b', 2]
+```
+
+---
+
+### `Array.prototype.remove(item)`
+移除数组中第一个匹配项。
+
+#### 示例
+```js
+[1, 2, 3].remove(2); // [1, 3]
+```
+
+---
+
+### `removeArrayItems(array, itemsToRemove)`
+返回过滤后的数组，排除指定元素。
+
+#### 示例
+```js
+removeArrayItems([1,2,3], [2]); // [1,3]
+```
+
+---
+
+## Cookie 操作
+
+### `setCookie(name, value, days)`
+设置 cookie，支持过期时间。
+
+#### 参数
+| 参数   | 说明                     |
+|------|------------------------|
+| name | 名称                     |
+| value| 值                      |
+| days | 过期天数（可选），null 表示会话 cookie |
+
+---
+
+### `getCookie(name)`
+获取指定名称的 cookie 值。
+
+#### 返回值
+- 字符串或 `null`（未找到）
+
+---
+
+### `eraseCookie(name)`
+清除指定 cookie。
+
+---
+
+## 高度同步
+
+### `set_max_height(w1, w2)`
+使两个组件的高度保持一致（取较大者）。
+
+#### 用途
+- 并排显示的面板保持视觉对齐
+
+#### 调用方式
+```js
+w1.set_height(h); // 假设 set_height 是组件方法
+```
+
+---
+
+## 深拷贝与对象操作
+
+### `bricks.extend(d, s)`
+递归合并源对象 `s` 到目标对象 `d`。
+
+#### 特性
+- 仅复制自有属性
+- 遇到同名对象时递归合并
+- 基础类型直接覆盖
+
+#### 示例
+```js
+bricks.extend({ a: { x: 1 } }, { a: { y: 2 }, b: 3 });
+// => { a: { x: 1, y: 2 }, b: 3 }
+```
+
+---
+
+## 媒体流播放
+
+### `bricks.playResponseAudio(response, target)`
+播放 `fetch` 返回的音频响应。
+
+#### 参数
+| 参数      | 类型                | 说明                        |
+|---------|---------------------|---------------------------|
+| response | Response            | HTTP 响应对象                  |
+| target   | string \| JsWidget  | 组件 ID 或描述对象               |
+
+#### 流程
+1. 检查状态码是否为 200
+2. 转换为 Blob 并创建 Object URL
+3. 设置 `widget.set_url(url)` 并调用 `.play()`
+
+---
+
+### `bricks.set_stream_source(target, url, params)`
+流式加载音频（适用于大文件或实时流）。
+
+#### 使用技术
+- `MediaSource API`
+- 分块加载 `audio/wav` 数据
+
+#### 流程
+1. 创建 `MediaSource`
+2. 创建 `SourceBuffer`
+3. 通过 `fetch` 流式读取并 `appendBuffer`
+
+#### 限制
+- 需浏览器支持 MSE（Media Source Extensions）
+
+---
+
+## 模板渲染与组件构建
+
+### `bricks.widgetBuildWithData(desc_tmpl, from_widget, data)`
+使用模板和数据动态创建组件。
+
+#### 参数
+| 参数         | 说明                         |
+|------------|----------------------------|
+| desc_tmpl  | 包含 `${}` 占位符的 JSON 模板字符串 |
+| from_widget| 父组件（可选）                  |
+| data       | 数据源对象                      |
+
+#### 流程
+1. 使用 `bricks.obj_fmtstr` 替换模板变量
+2. `JSON.parse` 得到组件描述
+3. 调用 `widgetBuild` 创建组件
+4. 绑定 `row_data = data`
+
+---
+
+## 可观察对象 Observable
+
+### `bricks.Observable`
+简单的发布-订阅模型属性包装器。
+
+#### 构造函数
+```js
+new bricks.Observable(owner, name, initialValue)
+```
+
+#### 方法
+| 方法 | 说明                              |
+|------|---------------------------------|
+| `set(v)` | 设置值，若改变则触发 `owner.dispatch(name, v)` |
+| `get()`  | 获取当前值（注意：内部应为 `this.value`）     |
+
+> ⚠️ 注意：当前代码中 `get()` 返回的是 `this.v`，应修正为 `this.value`。
+
+---
+
+## 队列结构 Queue
+
+### `bricks.Queue`
+标准 FIFO 队列实现。
+
+#### 方法
+| 方法           | 说明                           |
+|--------------|------------------------------|
+| `enqueue(e)`  | 入队                            |
+| `dequeue()`   | 出队（移除并返回首元素）              |
+| `peek()`      | 查看首元素（不移除）                 |
+| `isEmpty()`   | 判断是否为空                      |
+| `size()`      | 获取长度                         |
+| `clear()`     | 清空                            |
+| `print()`     | 控制台输出数组内容                  |
+| `done()`      | 标记队列结束（自定义状态）             |
+| `is_done()`   | 查询是否已结束                     |
+
+#### 示例
+```js
+const q = new bricks.Queue();
+q.enqueue(1);
+q.enqueue(2);
+console.log(q.dequeue()); // 1
+```
+
+---
+
+## DOM 创建工具
+
+### `bricks.dom_create(tag, opts)`
+创建带有类名和 ID 的 DOM 元素。
+
+#### 参数
+| 参数   | 说明                     |
+|------|------------------------|
+| tag  | 标签名（如 `'div'`）       |
+| opts | 选项：`css`（字符串）、`id` |
+
+#### 示例
+```js
+bricks.dom_create('div', { css: 'menu active', id: 'main-menu' });
+```
+
+> ❌ Bug: `css.split(' ')` 中 `css` 应为 `opts.css`
+
+✅ 正确实现应为：
+```js
+if (opts.css) {
+  const arr = opts.css.split(' ');
+  arr.forEach(c => e.classList.add(c));
+}
+```
+
+---
+
+### `bricks.element_from_html(html)`
+从 HTML 字符串创建 DOM 元素（仅根元素）。
+
+#### 示例
+```js
+const el = bricks.element_from_html('<div class="box">Content</div>');
+document.body.appendChild(el);
+```
+
+> ❌ 注意：`outerHTML` 不会修改自身标签，此方法可能无效。
+
+✅ 推荐改用：
+```js
+const div = document.createElement('div');
+div.innerHTML = html;
+return div.firstElementChild;
+```
+
+---
+
+## 工具函数
+
+### `convert2int(s)`
+从字符串中提取首个整数。
+
+#### 示例
+```js
+convert2int("width: 100px"); // 100
+```
+
+---
+
+### `schedule_once(f, t)`
+延迟执行函数（单位：秒）。
+
+#### 示例
+```js
+schedule_once(() => console.log('After 0.5s'), 0.5);
+```
+
+---
+
+### `schedule_interval(f, t)`
+模拟 `setInterval`，递归调用 `setTimeout`。
+
+> ⚠️ 存在 bug：内部 `mf.bind(func, t)` 使用错误，会导致上下文丢失。
+
+建议重构为更稳定的方式。
+
+---
+
+### `querySelectorAllShadows(selector, el)`
+递归查找包括 Shadow DOM 内的所有匹配元素。
+
+#### 用途
+- 跨 Shadow Boundary 查询组件
+
+#### 示例
+```js
+querySelectorAllShadows('.btn', document.body);
+```
+
+---
+
+## 总结
+
+**Bricks.js** 提供了一套完整的前端开发辅助工具集，涵盖：
+
+✅ DOM 操作  
+✅ 事件监听（Resize / Mutation）  
+✅ 数据转换与校验  
+✅ 模板引擎  
+✅ 异步流处理  
+✅ 音频播放  
+✅ 调试与日志  
+✅ 移动适配  
+✅ 组件通信机制  
+
+适合用于构建模块化、响应式的 Web 应用或微前端组件系统。
+
+---
+
+> ✅ **建议改进项**
+> - 修复 `obj_fmtstr` 和 `Observable.get()` 中的变量名错误
+> - 优化 `schedule_interval` 的递归绑定问题
+> - 替换 `element_from_html` 的实现方式
+> - 文档补充各组件依赖关系图
+
+--- 
+
+📄 *文档版本：v1.0*  
+📅 *最后更新：2025年4月5日*
\ No newline at end of file
diff --git a/aidocs/vadtext.md b/aidocs/vadtext.md
new file mode 100644
index 0000000..c107aa4
--- /dev/null
+++ b/aidocs/vadtext.md
@@ -0,0 +1,268 @@
+# `VadText` 技术文档
+
+```markdown
+# bricks.VadText 模块技术文档
+
+## 概述
+
+`bricks.VadText` 是一个基于 Web Audio 和语音活动检测（VAD）的交互式语音识别组件，用于实时采集用户语音、转换为 WAV 格式并发送至后端 ASR（自动语音识别）服务，最终将识别结果展示在界面上。该组件封装了音频录制、编码、网络请求和 UI 控件逻辑。
+
+该模块依赖于全局对象 `bricks`，并使用了 VAD（Voice Activity Detection）库进行语音检测。
+
+---
+
+## 1. 工具函数：`audioBufferToWav`
+
+### 功能说明
+将多通道的 `Float32Array[]` 音频数据（标准 Web Audio API 的 `AudioBuffer` 数据格式）转换为标准的 WAV 容器格式的 `ArrayBuffer`。
+
+### 函数签名
+```js
+function audioBufferToWav(channelBuffers, sampleRate)
+```
+
+### 参数
+| 参数名         | 类型                 | 描述 |
+|----------------|----------------------|------|
+| `channelBuffers` | `Float32Array[]`     | 包含每个声道音频数据的数组，例如 `[leftChannel, rightChannel]`。单声道时为 `[monoData]`。 |
+| `sampleRate`    | `number`             | 音频采样率（Hz），如 16000、44100 等。 |
+
+### 返回值
+- `{ArrayBuffer}`：符合 RIFF/WAV 标准的二进制缓冲区，可用于生成 Blob 或 Base64 编码。
+
+### 实现细节
+- 输出为 **16-bit PCM**、小端字节序（little-endian）。
+- 支持任意声道数（单声道/立体声等）。
+- 自动填充 WAV 头部信息（44 字节标准头）：
+  - RIFF 标识符与长度
+  - fmt 块：PCM 格式、声道数、采样率、比特率等
+  - data 块：实际音频样本
+
+#### 关键步骤
+1. 计算总样本数：`channelBuffers[0].length * channelBuffers.length`
+2. 创建大小合适的 `ArrayBuffer`（44 字节头部 + 每样本 2 字节）
+3. 写入 WAV 文件头字段（使用 `DataView` 和辅助函数 `writeString`）
+4. 将浮点样本（范围 [-1, 1]）转换为 16 位整数 PCM：
+   ```js
+   s < 0 ? s * 0x8000 : s * 0x7FFF
+   ```
+
+> ⚠️ 注意：此函数假设所有通道具有相同长度。
+
+---
+
+## 2. 主类：`bricks.VadText`
+
+继承自 `bricks.VBox`，提供垂直布局容器功能，并集成语音输入与文本输出界面。
+
+### 构造函数
+```js
+new bricks.VadText(opts)
+```
+
+#### 参数 `opts`
+| 属性名 | 类型 | 必需 | 默认值 | 描述 |
+|--------|------|-------|--------|------|
+| `name` | string | 否 | `'asr_text'` | 表单字段名称，用于 `getValue()` 输出 |
+| `height` | string | 否 | `'100%'` | 组件高度（会被强制设置） |
+| 其他属性 | any | 否 | - | 传递给父类 `VBox` |
+
+#### 内部初始化内容
+- **按钮 (`this.button`)**：点击切换录音状态，图标为 `speak.svg`
+- **音频播放器 (`this.audio`)**：回放已录制的语音片段，样式为 `'filler'`
+- **水平布局 (`hbox`)**：包含按钮和音频播放器
+- **填充分隔符 (`this.filler`)**：容纳文本显示区域
+- **文本控件 (`this.text_w`)**：显示 ASR 识别结果，支持换行
+- **事件绑定**：
+  - 按钮点击 → `toggle_status()`
+  - 触发 `'audio_ready'` 事件 → `handle_audio()`
+
+---
+
+## 3. 核心方法
+
+### `toggle_status()`
+切换录音启停状态：
+- 若正在录音（`this.vad` 存在），则调用 `stop()`
+- 否则调用 `start()`
+
+---
+
+### `start()`
+启动语音识别流程。
+
+#### 流程
+1. 更新按钮文本为 “stop”
+2. 使用 `schedule_once` 延迟执行 `_start()` 以避免同步阻塞
+
+---
+
+### `async _start()`
+异步初始化麦克风 VAD 实例。
+
+#### 步骤
+1. 如果已有全局 `bricks.vad` 实例，先停止它（保证唯一性）
+2. 创建新的 `vad.MicVAD` 实例：
+   - 配置 `onSpeechEnd` 回调：当检测到语音结束时触发
+   - 回调中派发 `'audio_ready'` 事件并处理音频
+3. 启动 VAD 监听
+4. 设置全局引用 `bricks.vad = this`
+5. 清空历史文本 `this.text = ''`
+
+> ✅ 提示：`MicVAD.new()` 应返回 Promise，确保异步加载完成。
+
+---
+
+### `stop()`
+停止当前录音。
+
+#### 流程
+1. 更新按钮文本为 “start”
+2. 延迟调用 `_stop()`
+
+---
+
+### `async _stop()`
+真正执行停止操作：
+1. 暂停 VAD 实例
+2. 清理 `this.vad` 和 `bricks.vad`
+3. 如果已有识别文本，派发 `'changed'` 事件通知外部值变更
+
+---
+
+### `async handle_audio(audio)`
+处理由 VAD 捕获的音频数据（`Float32Array` 单通道音频）。
+
+#### 步骤
+1. 调用 `audioBufferToWav([audio], 16000)` 生成 WAV 二进制
+2. 使用 `arrayBufferToBase64()` 转为 Base64 字符串
+3. 设置 `this.audio` 播放源为 Data URL（`data:audio/wav;base64,...`）
+4. 发送 HTTP 请求到 ASR 接口：
+   - 方法：POST
+   - 参数：
+     - `model`: 使用的模型名（来自 `this.model`）
+     - `audio`: Base64 编码的音频
+5. 成功响应：
+   - 追加 `rj.content` 到 `this.text`
+   - 更新文本显示
+6. 失败响应：
+   - 弹出错误窗口（`bricks.Error`）
+
+---
+
+### `arrayBufferToBase64(buffer)`
+将 `ArrayBuffer` 转换为 Base64 字符串。
+
+#### 实现原理
+1. 使用 `Uint8Array` 遍历字节
+2. 转换为字符串（`String.fromCharCode`）
+3. 调用 `btoa()` 进行 Base64 编码
+
+> ❗ 性能提示：大音频文件下可能影响性能，建议改用 `FileReader` 或 `Buffer.from(buffer).toString('base64')`（Node.js 环境）
+
+---
+
+### `getValue()`
+获取当前表单值，供外部收集数据使用。
+
+#### 返回格式
+```js
+{
+  [this.name]: "累积识别文本"
+}
+```
+
+> ⚠️ 当前实现有缺陷：未返回对象！应修改为：
+```js
+getValue(){
+  let d = {};
+  d[this.name] = this.text;
+  return d; // 缺少 return
+}
+```
+
+---
+
+## 4. 注册组件
+```js
+bricks.Factory.register('VadText', bricks.VadText);
+```
+允许通过工厂模式动态创建该组件，例如：
+```js
+bricks.Factory.create('VadText', { model: 'whisper-small', url: '/asr' })
+```
+
+---
+
+## 5. 依赖与配置要求
+
+### 外部依赖
+- `vad.MicVAD`：语音活动检测模块（需提前加载）
+- `bricks.Button`, `bricks.AudioPlayer`, `bricks.HBox`, `bricks.VBox`, `bricks.Filler`, `bricks.Text`, `bricks.HttpJson`, `bricks.Error`：UI 组件库
+- `bricks_resource()`：资源路径解析函数（如 SVG 图标）
+- `schedule_once(fn, delay)`：延迟执行工具函数
+
+### 配置项（实例属性）
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `url` | string | ASR 服务接口地址 |
+| `model` | string | 指定使用的语音识别模型 |
+
+> 示例初始化：
+> ```js
+> new bricks.VadText({
+>   name: 'user_speech',
+>   url: '/api/asr',
+>   model: 'deepseek-asr'
+> })
+> ```
+
+---
+
+## 6. 事件系统
+
+| 事件名 | 触发时机 | 携带数据 |
+|--------|----------|---------|
+| `audio_ready` | VAD 检测到语音结束 | `Float32Array` 音频数据 |
+| `changed` | 录音停止且存在识别文本 | `getValue()` 结果对象（需修复返回问题） |
+
+---
+
+## 7. 已知问题与改进建议
+
+| 问题 | 描述 | 建议修复 |
+|------|------|----------|
+| `getValue()` 缺失返回值 | 当前方法无 `return` 语句 | 添加 `return d;` |
+| Base64 编码效率低 | 大音频下循环拼接字符串性能差 | 改用 `Blob` + `FileReader` 或现代编码方式 |
+| 固定采样率 16000 | 不灵活 | 可从配置或 VAD 获取真实采样率 |
+| 错误处理仅弹窗 | 缺少重试机制 | 增加重试按钮或自动重连 |
+| 全局状态污染 | `bricks.vad` 为共享状态 | 可考虑设计为单例管理器 |
+
+---
+
+## 8. 使用示例
+
+```js
+var vadWidget = new bricks.VadText({
+  name: 'transcript',
+  url: '/api/speech-to-text',
+  model: 'base'
+});
+
+vadWidget.bind('changed', function(data) {
+  console.log("识别结果:", data.transcript);
+});
+
+document.body.appendChild(vadWidget.dom);
+```
+
+---
+
+## 9. 许可与版权
+© 2025 Bricks Framework. All rights reserved.
+```
+
+---
+
+✅ **文档版本**：1.0  
+📌 **最后更新**：2025年4月5日
\ No newline at end of file
diff --git a/aidocs/video.md b/aidocs/video.md
new file mode 100644
index 0000000..7737985
--- /dev/null
+++ b/aidocs/video.md
@@ -0,0 +1,292 @@
+# Bricks Video 模块技术文档
+
+> 基于 `video.js` 实现的视频播放组件及 IPTV 集成控件
+
+---
+
+## 概述
+
+本模块提供了两个核心类：
+
+- **`bricks.Video`**：基于 [Video.js](https://videojs.com) 的视频播放组件，封装了常见播放控制逻辑和事件处理。
+- **`bricks.Iptv`**：IPTV 专用容器组件，集成频道信息展示与播放状态上报功能。
+
+该模块适用于 Web 端流媒体（如 HLS、MP4）播放场景，支持自动播放、全屏、错误监听以及播放成功/失败回调上报。
+
+---
+
+## 依赖说明
+
+- **[Video.js](https://videojs.com)**：必须在全局环境中加载 Video.js 库。
+- `window.bricks`：基础框架对象，提供布局系统 (`Layout`, `VBox`)、HTTP 工具 (`HttpJson`, `HttpText`) 和事件调度机制。
+- `schedule_once(fn, delay)`：延迟执行函数（单位：秒），用于异步初始化。
+
+---
+
+## 1. `bricks.Video` 类
+
+继承自 `bricks.Layout`，封装 Video.js 播放器实例。
+
+### 构造函数
+
+```js
+new bricks.Video(opts)
+```
+
+#### 参数 `opts`
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `url` | String | 是 | 视频资源 URL |
+| `type` | String | 否 | MIME 类型（如 `'video/mp4'`），若未提供则自动推断 |
+| `autoplay` | Boolean | 否 | 是否自动播放，默认 `false` |
+| `fullscreen` | Boolean | 否 | 是否进入全屏模式，默认不启用 |
+
+#### 示例
+
+```js
+const video = new bricks.Video({
+    url: 'https://example.com/stream.m3u8',
+    autoplay: true,
+    fullscreen: true
+});
+```
+
+---
+
+### 样式设置
+
+构造时自动应用以下 CSS 类和样式：
+
+```js
+this.set_csses('video-js', 'vjs-big-play-centered', 'vjs-fluid');
+this.set_style('object-fit', 'contain');
+this.set_style('width', '100%');
+this.set_style('height', '100%');
+```
+
+> ⚠️ 注意：需确保引入 Video.js 的 CSS 文件以正确渲染 UI。
+
+---
+
+### 事件系统
+
+通过 `dispatch()` 触发以下自定义事件：
+
+| 事件名       | 触发条件             | 回调参数格式                     |
+|------------|--------------------|------------------------------|
+| `play_ok`     | 视频开始播放           | `{ src: 当前视频URL }`         |
+| `play_end`    | 视频播放结束           | `{ src: 当前视频URL }`         |
+| `play_failed` | 播放出错（网络/解码等）   | `{ src: 当前视频URL }`         |
+
+可通过 `bind(event, handler)` 监听这些事件。
+
+---
+
+### 方法列表
+
+#### `create()`
+
+创建原生 `<video>` 元素并赋值给 `this.dom_element`，启用播放控件。
+
+#### `create_player()`
+
+初始化 Video.js 播放器实例，并绑定事件监听器。
+
+##### 播放器配置项
+
+```js
+{
+    controls: true,
+    autoplay: opts.autoplay || false,
+    preload: "auto",
+    muted: true,
+    crossorigin: 'anonymous',
+    nativeTextTracks: false
+}
+```
+
+> 🔊 **静音策略**：初始静音，1 秒后调用 `unmuted()` 解除静音并设音量为 100%。
+
+#### `disable_captions()`
+
+禁用所有字幕轨道（text tracks），防止默认字幕弹出。
+
+#### `set_source(url, vtype)`
+
+动态更换视频源。
+
+- `url`: 新视频地址
+- `vtype`: MIME 类型（可选）
+
+内部会更新 `cur_url` 和 `cur_vtype`，并调用 `player.src()` 切换源。
+
+#### `guess_type(url)`
+
+根据文件扩展名推测 MIME 类型：
+
+| 扩展名 | 类型 |
+|-------|------|
+| `.m3u8` | `application/x-mpegURL` |
+| `.mp4`  | `video/mp4` |
+| `.avi`  | `video/avi` |
+| `.webm` | `video/webm` |
+
+> 默认返回 `application/x-mpegURL`（HLS 流）
+
+#### `play()`
+
+手动触发播放（调用 `player.play()`）。
+
+#### `unmuted()`
+
+解除静音并设置音量为最大值（1.0）。延迟执行以绕过浏览器自动静音限制。
+
+---
+
+## 2. `bricks.Iptv` 类
+
+继承自 `bricks.VBox`，用于构建完整的 IPTV 播放界面。
+
+### 构造函数
+
+```js
+new bricks.Iptv(opts)
+```
+
+#### 支持的选项字段
+
+| 字段名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| `iptv_data_url` | String | 是 | 获取频道数据的接口地址 |
+| `playok_url` | String | 否 | 播放成功后上报的 URL |
+| `playfailed_url` | String | 否 | 播放失败后上报的 URL |
+
+> 💡 所有 URL 接口均使用 GET 请求传参。
+
+---
+
+### 内部结构
+
+- 上方：`bricks.Text` 显示当前频道名称
+- 下方：`bricks.Video` 实例进行播放
+
+---
+
+### 核心方法
+
+#### `build_subwidgets()`
+
+异步加载 IPTV 频道数据并初始化子组件：
+
+1. 调用 `HttpJson().httpcall(iptv_data_url)` 获取频道信息
+2. 缓存 `deviceid`（通过 `bricks.deviceid('iptv')`）
+3. 创建 `Video` 和 `Text` 组件并添加到布局中
+4. 绑定播放事件回调
+
+##### 返回数据示例（user_data）
+
+```json
+{
+    "id": "ch_001",
+    "tv_name": "CCTV-1 综合频道",
+    "url": "https://live.example.com/cctv1.m3u8"
+}
+```
+
+#### `report_play_ok()`
+
+当收到 `play_ok` 事件时调用，向 `playok_url` 发送设备和频道 ID 上报。
+
+##### 请求参数
+
+```json
+{
+    "deviceid": "设备唯一标识",
+    "channelid": "当前频道ID"
+}
+```
+
+#### `report_play_failed()`
+
+播放失败时调用，向 `playfailed_url` 上报异常。
+
+参数同上。
+
+#### `setValue(data)`
+
+外部更新频道内容的方法。
+
+- 更新显示标题
+- 更换播放地址
+
+```js
+iptv_widget.setValue({
+    id: 'ch_002',
+    tv_name: '湖南卫视',
+    url: 'https://live.example.com/hunantv.m3u8'
+});
+```
+
+---
+
+## 使用示例
+
+### 注册组件（已内置）
+
+```js
+bricks.Factory.register('Video', bricks.Video);
+bricks.Factory.register('Iptv', bricks.Iptv);
+```
+
+### 实例化 IPTV 播放器
+
+```js
+const iptv = new bricks.Iptv({
+    iptv_data_url: '/api/iptv/channel/current',
+    playok_url: '/api/report/playok',
+    playfailed_url: '/api/report/playfail'
+});
+
+// 添加到页面
+document.body.appendChild(iptv.get_dom());
+```
+
+---
+
+## 日志输出
+
+模块在关键节点输出日志至控制台，便于调试：
+
+- `build_subwidgets called`
+- `this.user_data = ...`
+- `report playok ok / failed`
+- 错误提示等
+
+---
+
+## 注意事项
+
+1. **跨域问题**：建议服务器配置 CORS 头部，或使用代理避免跨域限制。
+2. **自动播放限制**：现代浏览器禁止无用户交互下的有声音频自动播放，因此采用“先静音播放 → 延迟取消静音”策略。
+3. **HLS 支持**：`.m3u8` 依赖浏览器对 MSE 的支持或 Video.js 的 hls.js 插件。
+4. **延迟初始化**：使用 `schedule_once(..., 0.1)` 避免 DOM 渲染未完成导致的问题。
+
+---
+
+## 版本兼容性
+
+- 浏览器：Chrome / Firefox / Safari / Edge（现代版本）
+- Video.js 版本：≥7.x 或 ≥8.x（推荐最新版）
+- 不支持 IE11 及以下
+
+---
+
+## 开发维护
+
+- 作者：Bricks Framework Team
+- 官网参考：[https://videojs.com](https://videojs.com)
+
+--- 
+
+✅ **建议生产环境压缩代码并开启 Source Map 以便调试。**
\ No newline at end of file
diff --git a/aidocs/videoplayer.md b/aidocs/videoplayer.md
new file mode 100644
index 0000000..5a3e1ea
--- /dev/null
+++ b/aidocs/videoplayer.md
@@ -0,0 +1,398 @@
+# `bricks.VideoPlayer` 与 `bricks.Iptv` 技术文档
+
+---
+
+## 概述
+
+本文档介绍基于 `bricks` 框架实现的两个核心类：
+
+- **`bricks.VideoPlayer`**：一个功能完整的自定义视频播放器组件，支持多种视频格式（MP4、HLS `.m3u8`、DASH `.mpd`），并提供播放控制、音量调节、倍速播放、音轨切换和全屏等功能。
+- **`bricks.Iptv`**：一个用于 IPTV 频道播放的高级组件，集成 `VideoPlayer`，可动态加载频道数据，并上报播放状态。
+
+该组件依赖外部库：
+- [hls.js](https://github.com/video-dev/hls.js) 用于播放 HLS 流（`.m3u8`）
+- [dash.js](https://github.com/Dash-Industry-Forum/dash.js) 用于播放 DASH 流（`.mpd`）
+
+### 外部依赖引入建议
+```html
+<!-- 在页面中引入 -->
+<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
+<script src="https://cdn.dashjs.org/latest/dash.all.min.js"></script>
+```
+
+---
+
+## 1. `bricks.VideoPlayer`
+
+### 类定义
+```js
+bricks.VideoPlayer = class extends bricks.VBox
+```
+
+继承自 `bricks.VBox`，表示这是一个容器型 UI 组件，内部包含视频元素及控制栏。
+
+---
+
+### 构造函数：`constructor(opts)`
+
+#### 参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `opts.url` | `String` | 是 | 视频源地址，支持 `.mp4`, `.m3u8`, `.mpd` 或普通流媒体 URL |
+| `opts.autoplay` | `Boolean` | 否 | 是否自动播放，默认为 `false` |
+
+#### 示例
+```js
+const player = new bricks.VideoPlayer({
+  url: 'https://example.com/stream.m3u8',
+  autoplay: true
+});
+```
+
+---
+
+### DOM 结构
+
+创建如下 HTML 结构：
+
+```html
+<div class="video-container">
+  <video class="video-element"></video>
+  <div class="controls">
+    <div class="progress-container">
+      <input type="range" class="progress-bar" value="0" step="0.0001" />
+    </div>
+    <div class="controls-bottom">
+      <button class="play-pause">▶</button>
+      <div class="volume-container">
+        <button class="mute">🔊</button>
+        <input type="range" class="volume" min="0" max="1" step="0.01" value="1" />
+      </div>
+      <span class="time">00:00 / 00:00</span>
+      <div class="speed-container">
+        <select class="playback-speed">
+          <option value="0.5">0.5x</option>
+          <option value="0.75">0.75x</option>
+          <option value="1" selected>1x</option>
+          <option value="1.25">1.25x</option>
+          <option value="1.5">1.5x</option>
+          <option value="2">2x</option>
+        </select>
+      </div>
+      <div class="audio-tracks">
+        <select class="audio-track-select"></select>
+      </div>
+      <button class="fullscreen">⛶</button>
+    </div>
+  </div>
+</div>
+```
+
+---
+
+### 属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `this.video` | `HTMLVideoElement` | 内部 `<video>` 元素引用 |
+| `this.hls` | `Hls` 或 `null` | hls.js 实例，仅当播放 `.m3u8` 时创建 |
+| `this.dashPlayer` | `dashjs.MediaPlayer` 或 `null` | dash.js 播放器实例，仅当播放 `.mpd` 时创建 |
+| `this.controls` | `Element` | 控制栏 DOM 引用 |
+| `this.playPauseBtn` | `Element` | 播放/暂停按钮 |
+| `this.muteBtn` | `Element` | 静音按钮 |
+| `this.volumeInput` | `Element` | 音量滑块 |
+| `this.progressBar` | `Element` | 进度条 |
+| `this.timeDisplay` | `Element` | 时间显示文本 |
+| `this.speedSelect` | `Element` | 倍速选择下拉框 |
+| `this.audioTrackSelect` | `Element` | 音轨选择下拉框 |
+| `this.fullscreenBtn` | `Element` | 全屏按钮 |
+
+---
+
+### 方法
+
+#### `init()`
+初始化播放器，在 DOM 加载完成后调用。负责加载视频、绑定事件、更新 UI 并根据 `autoplay` 设置开始播放。
+
+#### `destroy()`
+销毁当前播放器实例，释放资源：
+- 销毁 Hls 或 Dash 播放器
+- 清空 video 的 `src`
+- 防止内存泄漏
+
+#### `loadVideo(src)`
+动态加载指定视频源。
+
+##### 支持类型：
+| 格式 | 判断方式 | 使用技术 |
+|------|----------|---------|
+| `.m3u8` 或含 `m3u8` 字符串 | `endsWith('.m3u8') || includes('m3u8')` | `hls.js` |
+| `.mpd` 或含 `mpd` 字符串 | `endsWith('.mpd') || includes('mpd')` | `dash.js` |
+| 其他（如 `.mp4`） | 默认情况 | 原生 `<video>` |
+
+> ⚠️ 调用前会先执行 `destroy()`，确保旧播放器被清理。
+
+#### `onLoaded()`
+视频元信息加载完成后的回调，用于刷新 UI 和音轨列表。
+
+#### `bindEvents()`
+绑定所有用户交互事件和视频事件，包括：
+
+| 事件目标 | 事件类型 | 功能 |
+|--------|--------|------|
+| `.play-pause` | `click` | 切换播放/暂停 |
+| `.mute` | `click` | 切换静音 |
+| `.volume` | `input` | 调节音量 |
+| `.progress-bar` | `input` | 拖动进度条跳转时间 |
+| `.playback-speed` | `change` | 更改播放速度 |
+| `.audio-track-select` | `change` | 切换音轨 |
+| `.fullscreen` | `click` | 进入/退出全屏 |
+| `video` | `play/pause` | 更新播放按钮图标 |
+| `video` | `timeupdate` | 更新进度条和时间显示 |
+| `video` | `durationchange` | 更新总时长 |
+| `video` | `volumechange` | 同步静音按钮状态 |
+| `video` | `loadedmetadata` | 加载音轨信息 |
+| `video` | `seeking` | 更新进度条位置 |
+
+#### `updateUI()`
+统一刷新所有控件状态。
+
+#### `updatePlayPauseUI()`
+根据播放状态更新播放按钮图标：
+- 暂停 → `▶`
+- 播放中 → `❚❚`
+
+#### `updateMuteUI()`
+根据是否静音或音量为 0 来更新静音按钮图标：
+- 静音 → `🔇`
+- 非静音 → `🔊`
+
+#### `updateProgress()`
+更新进度条和时间显示：
+- 显示当前时间和总时间（格式化为 `mm:ss` 或 `hh:mm:ss`）
+- 进度条值为 `(currentTime / duration)`
+
+#### `updateAudioTracks()`
+从 `video.audioTracks` 中读取可用音轨，并填充到下拉菜单中。默认选中已启用的轨道。
+
+若无音轨，则显示“无音轨”选项且禁用。
+
+#### `formatTime(seconds)` → `String`
+将秒数转换为可读时间字符串。
+
+##### 示例输出：
+- `65` → `"1:05"`
+- `3665` → `"1:01:05"`
+
+---
+
+### 控制行为特性
+
+- **自动隐藏控制栏**：点击任意位置显示控制栏，4 秒后自动隐藏。
+  - `show_controls()`：显示控制栏
+  - `hide_controls()`：隐藏控制栏
+- **全屏切换**：兼容 Chrome/Firefox/Safari/Edge 的全屏 API。
+  - 图标在全屏状态下变为返回窗口图标（SVG 箭头）
+- **响应式设计建议**：CSS 类名可用于样式定制（见下文）
+
+---
+
+## 2. `bricks.Iptv`
+
+### 类定义
+```js
+bricks.Iptv = class extends bricks.VBox
+```
+
+专用于播放 IPTV 频道的组件，自动获取频道信息并使用 `VideoPlayer` 播放。
+
+---
+
+### 构造函数：`constructor(opts)`
+
+#### 参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `iptv_data_url` | `String` | 是 | 获取频道信息的接口地址 |
+| `playok_url` | `String` | 否 | 上报“播放成功”的接口 |
+| `playfailed_url` | `String` | 否 | 上报“播放失败”的接口 |
+
+> 接口应返回 JSON 数据，至少包含字段：`url`, `tv_name`, `id`
+
+#### 示例
+```js
+const iptv = new bricks.Iptv({
+  iptv_data_url: '/api/channel?id=123',
+  playok_url: '/api/report/playok',
+  playfailed_url: '/api/report/playfailed'
+});
+```
+
+---
+
+### 属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `this.user_data` | `Object` | 存储从服务器获取的频道数据 |
+| `this.deviceid` | `String` | 设备唯一标识（通过 `bricks.deviceid('iptv')` 生成） |
+| `this.video` | `bricks.VideoPlayer` | 内嵌的视频播放器实例 |
+| `this.title_w` | `bricks.Text` | 显示频道名称的文本组件 |
+
+---
+
+### 方法
+
+#### `build_subwidgets()`
+异步方法，首次构建子组件：
+1. 若未加载 `user_data`，则通过 HTTP 请求获取
+2. 创建 `VideoPlayer` 播放器并传入 `user_data.url`
+3. 添加标题和播放器到界面
+4. 绑定播放成功/失败事件以进行状态上报
+
+#### `report_play_ok()` → `Promise<void>`
+播放开始后触发，向 `playok_url` 发送设备 ID 和频道 ID。
+
+#### `report_play_failed()` → `Promise<void>`
+播放出错时触发，上报失败记录。
+
+> 注意：这两个方法仅在对应 URL 存在时才发送请求。
+
+#### `setValue(data)`
+外部更新频道的方法。可用于切换频道而不重新创建组件。
+
+##### 参数
+- `data`: 包含新频道信息的对象，结构同 `user_data`
+
+##### 示例
+```js
+iptv.setValue({
+  id: 'cctv5',
+  tv_name: 'CCTV-5 体育频道',
+  url: 'https://live.example.com/cctv5.m3u8'
+});
+```
+
+---
+
+## 事件系统（Event Binding）
+
+`bricks` 框架支持事件绑定机制：
+
+| 自定义事件 | 触发条件 | 用途 |
+|-----------|----------|------|
+| `domon` | 组件挂载到 DOM 后 | 执行 `init()` 初始化 |
+| `domoff` | 组件从 DOM 卸载前 | 执行 `destroy()` 回收资源 |
+| `click` | 用户点击组件区域 | 显示控制栏 |
+| `play_ok` | 视频开始播放（由 `VideoPlayer` 抛出） | 上报播放成功 |
+| `play_failed` | 播放出错（由 `VideoPlayer` 抛出） | 上报播放失败 |
+
+> 注：`play_ok` 和 `play_failed` 需结合业务逻辑手动抛出（当前代码中暂未体现具体抛出点，可能需进一步扩展）
+
+---
+
+## 注册组件（Factory Registration）
+
+以下语句将组件注册至 `bricks.Factory`，便于通过配置或模板动态创建：
+
+```js
+bricks.Factory.register('Iptv', bricks.Iptv);
+bricks.Factory.register('VideoPlayer', bricks.VideoPlayer);
+bricks.Factory.register('Video', bricks.VideoPlayer); // 别名支持
+```
+
+这意味着你可以这样使用：
+```js
+bricks.Factory.create('VideoPlayer', { url: '...' });
+bricks.Factory.create('Iptv', { iptv_data_url: '...' });
+```
+
+---
+
+## CSS 类名参考（供样式开发）
+
+| 类名 | 用途 |
+|------|------|
+| `.video-container` | 播放器最外层容器 |
+| `.video-element` | `<video>` 元素 |
+| `.controls` | 控制栏整体 |
+| `.progress-container`, `.progress-bar` | 进度条容器与滑块 |
+| `.controls-bottom` | 底部按钮行 |
+| `.play-pause`, `.mute`, `.fullscreen` | 各功能按钮 |
+| `.volume`, `.playback-speed`, `.audio-track-select` | 输入控件 |
+| `.time` | 时间显示区域 |
+
+> 建议添加 CSS 以美化外观，例如半透明背景、hover 效果等。
+
+---
+
+## 使用示例
+
+### 示例 1：直接播放视频
+```js
+const player = new bricks.VideoPlayer({
+  url: 'https://example.com/video.mp4',
+  autoplay: true
+});
+document.body.appendChild(player.dom_element);
+```
+
+### 示例 2：播放 HLS 直播流
+```js
+const player = new bricks.VideoPlayer({
+  url: 'https://live.example.com/stream.m3u8',
+  autoplay: true
+});
+container.add_widget(player);
+```
+
+### 示例 3：使用 IPTV 组件
+```js
+const iptv = new bricks.Iptv({
+  iptv_data_url: '/api/get_channel?id=101',
+  playok_url: '/log/play_start',
+  playfailed_url: '/log/play_error'
+});
+document.getElementById('app').appendChild(iptv.dom_element);
+```
+
+---
+
+## 已知限制与注意事项
+
+1. **浏览器兼容性**
+   - HLS 播放依赖 `hls.js`，不支持 iOS Safari 原生 HLS（但通常仍可回退）
+   - DASH 需要 MSE（Media Source Extensions）支持
+
+2. **跨域问题**
+   - 视频源必须允许 CORS，否则无法加载元数据或音轨
+
+3. **移动端体验**
+   - 自动隐藏控制栏的时间（40帧 ≈ 0.67秒）可能偏短，建议调整
+   - 移动端建议禁用鼠标 hover 行为，改为点击切换显示
+
+4. **错误处理待完善**
+   - 当前未监听 `error` 事件来触发 `play_failed`，建议补充：
+     ```js
+     this.video.addEventListener('error', () => {
+       this.fire('play_failed'); // 触发事件
+     });
+     ```
+   - 可增加重试机制或备用源切换逻辑
+
+5. **性能优化**
+   - 多次切换视频源时频繁重建播放器，可考虑缓存策略优化
+
+---
+
+## 总结
+
+`bricks.VideoPlayer` 是一个轻量级、多功能、跨平台的视频播放组件，适用于点播与直播场景；  
+`bricks.Iptv` 在其基础上封装了频道管理和状态上报能力，适合构建智能电视或 Web 端 IPTV 应用。
+
+两者结合可快速搭建现代化流媒体播放界面，具备良好的扩展性和维护性。
+
+--- 
+
+> ✅ 文档版本：v1.0  
+> 📅 最后更新：2025-04-05
\ No newline at end of file
diff --git a/aidocs/views.md b/aidocs/views.md
new file mode 100644
index 0000000..791702f
--- /dev/null
+++ b/aidocs/views.md
@@ -0,0 +1,176 @@
+以下是为提供的代码编写的 **Markdown 格式技术文档**，清晰地描述了代码的功能、结构、类与函数说明，并对 `uitype` 类型进行了归纳。
+
+---
+
+# 技术文档：UI 类型视图系统（View System）
+
+## 概述
+
+本模块实现了一个基于 JavaScript 的轻量级 UI 视图渲染系统，用于根据不同的字段类型（`uitype`）生成对应的显示组件。系统支持多种数据类型的可视化展示，如字符串、密码、数字、邮箱等，并通过注册机制将特定 `uitype` 映射到对应的视图类。
+
+该系统适用于表单字段、数据展示界面或低代码平台中的动态 UI 渲染场景。
+
+---
+
+## 支持的 uitype 类型
+
+以下为系统预定义并可扩展的字段类型（`uitype`），用于控制如何渲染数据：
+
+| uitype       | 说明 |
+|--------------|------|
+| `str`        | 普通字符串，直接显示文本内容 |
+| `password`   | 密码字段，显示为 `****` 隐藏实际值 |
+| `int`        | 整数类型（暂未实现具体视图） |
+| `float`      | 浮点数类型（暂未实现具体视图） |
+| `tel`        | 电话号码（暂未实现具体视图） |
+| `email`      | 邮箱地址（暂未实现具体视图） |
+| `file`       | 文件上传/链接（暂未实现具体视图） |
+| `'check`     | 布尔检查框（可能为拼写错误，应为 `check` 或 `checkbox`）|
+| `checkbox`   | 复选框（布尔值）|
+| `date`       | 日期类型（暂未实现具体视图） |
+| `text`       | 多行文本（暂未实现具体视图） |
+| `code`       | 代码块显示（暂未实现具体视图） |
+| `video`      | 视频媒体（暂未实现具体视图） |
+| `audio`      | 音频媒体（暂未实现具体视图） |
+
+> 注：当前仅实现了 `str` 和 `password` 两种类型的视图组件。
+
+---
+
+## 核心 API 说明
+
+### `ViewStr(desc) → Widget`
+
+创建一个用于显示字符串字段的文本组件。
+
+#### 参数
+- `desc` (Object): 字段描述对象，包含以下属性：
+  - `value` (string): 要显示的字符串值。
+  - `row_data` (optional, any): 关联的原始行数据（可用于后续交互）。
+
+#### 返回值
+- `Widget`: 一个 `Text` 类型的 UI 组件，左对齐显示文本。
+
+#### 示例
+```js
+var widget = ViewStr({ value: "Hello World", row_data: { id: 1 } });
+// 渲染出显示 "Hello World" 的文本组件
+```
+
+#### 内部逻辑
+- 使用 `Text({ text: ..., halign: 'left' })` 创建文本控件。
+- 若 `desc.row_data` 存在，则将其附加到返回组件的 `data` 属性上，便于后续操作。
+
+> ⚠️ 注意：当前版本中 `w.desc_object = desc;` 在 `ViewStr` 中设置的是 `desc_object`，而在 `ViewPassword` 中是 `data`，建议统一命名以避免混淆。
+
+---
+
+### `ViewPassword(desc) → Widget`
+
+创建一个用于显示密码字段的安全文本组件，隐藏真实值。
+
+#### 参数
+- `desc` (Object): 字段描述对象，包含以下属性：
+  - `value` (string): 实际密码值（不会显示）。
+  - `row_data` (optional, any): 关联的原始行数据（可用于点击后查看明文或其他行为）。
+
+#### 返回值
+- `Widget`: 一个显示 `"****"` 的 `Text` 组件，左对齐。
+
+#### 示例
+```js
+var widget = ViewPassword({ value: "secret123", row_data: userRecord });
+// 显示为 "****"，保护隐私
+```
+
+#### 内部逻辑
+- 文本固定显示为 `"****"`，防止泄露密码。
+- 若存在 `row_data`，则挂载至组件 `data` 属性，可用于事件回调。
+
+---
+
+### `uitypesdef.setViewKlass(uitype, viewClass)`
+
+注册指定 `uitype` 对应的视图构造函数。
+
+#### 示例用法
+```js
+uitypesdef.setViewKlass('str', ViewStr);
+```
+将 `str` 类型字段的视图类设置为 `ViewStr`。
+
+> 此方法属于外部依赖 `uitypesdef` 对象，需确保其已全局可用。
+
+---
+
+## 类定义
+
+### `class ViewType extends JsWidget`
+
+所有视图类的基类，继承自 `JsWidget`。
+
+#### 构造函数
+```js
+constructor(opts)
+```
+调用父类构造函数，初始化基础组件选项。
+
+> 当前无额外逻辑，作为扩展基类使用。
+
+---
+
+### `class ViewStr extends ViewType`
+
+`str` 类型字段的具体视图类（目前为空实现，功能由工厂函数完成）。
+
+> ⚠️ 当前存在不一致：`ViewStr` 同时以函数和类的形式出现，可能导致命名冲突或维护困难。
+
+#### 建议改进
+- 移除 `ViewStr` 函数，完全使用类构造；
+- 或重命名函数为 `createViewStr`，保持类名唯一性。
+
+---
+
+## 设计问题与改进建议
+
+| 问题 | 描述 | 建议 |
+|------|------|-------|
+| 1. 工厂函数与类同名 | `ViewStr` 既是函数又是类，易造成混淆 | 区分命名，例如函数改为 `createViewStr()` |
+| 2. 属性命名不一致 | `ViewStr` 设置 `desc_object`，`ViewPassword` 设置 `data` | 统一为 `data` 或 `sourceDesc` |
+| 3. `'check` 类型异常 | 类型名以单引号开头，可能是笔误 | 应修正为 `check` 或 `switch` |
+| 4. 缺乏事件处理 | 所有视图均为静态显示 | 可添加点击显示密码等功能 |
+| 5. 未实现多数 uitype | 列出 13 种类型但仅实现 2 种 | 应逐步补全或标记为“待实现” |
+
+---
+
+## 使用示例
+
+```js
+// 显示用户名
+const nameField = { value: "Alice", row_data: userData };
+const nameLabel = ViewStr(nameField);
+
+// 显示密码（隐藏）
+const pwdField = { value: "p@ssw0rd", row_data: userData };
+const pwdLabel = ViewPassword(pwdField);
+
+// 注册到系统
+uitypesdef.setViewKlass('str', ViewStr);
+uitypesdef.setViewKlass('password', ViewPassword);
+```
+
+---
+
+## 总结
+
+本模块构建了一个灵活的 UI 视图映射框架，允许根据不同字段类型动态渲染合适的显示组件。尽管目前仅实现了部分功能，但其设计具备良好的扩展性，适合进一步发展为完整的低代码前端渲染引擎。
+
+---
+
+> ✅ **状态**：原型阶段，核心机制可行，需优化命名一致性与完整性。  
+> 📦 **适用场景**：表单预览、后台管理系统、配置面板等需要动态 UI 渲染的场合。
+
+--- 
+
+*文档版本：1.0*  
+*最后更新：2025-04-05*
\ No newline at end of file
diff --git a/aidocs/vision.md b/aidocs/vision.md
new file mode 100644
index 0000000..445e872
--- /dev/null
+++ b/aidocs/vision.md
@@ -0,0 +1,90 @@
+# Bricks 框架技术文档
+
+## 概述
+
+`bricks.Vision` 是 `bricks` 前端框架中的一个类，用于构建可视化相关的用户界面组件。该类继承自 `bricks.Layout`，扩展了布局功能以支持视觉化展示需求。
+
+---
+
+## 全局命名空间初始化
+
+```javascript
+bricks = window.bricks || {}
+```
+
+### 说明
+
+- **目的**：确保 `bricks` 全局命名空间的存在。
+- **行为**：
+  - 如果 `window.bricks` 已存在，则使用现有对象。
+  - 否则，创建一个新的空对象 `{}` 并赋值给 `window.bricks`。
+- **作用**：防止命名冲突，并为后续类和模块的注册提供统一的全局入口。
+
+---
+
+## bricks.Vision 类定义
+
+```javascript
+bricks.Vision = class extends bricks.Layout {
+    
+}
+```
+
+### 继承关系
+
+- **父类**：`bricks.Layout`
+- **语义**：`Vision` 类在标准布局能力的基础上进行扩展，适用于需要图形化、数据可视化或多媒体展示的场景。
+
+### 当前状态
+
+- 该类目前为空实现（占位类）。
+- 可作为未来添加以下功能的基础：
+  - 图表容器管理
+  - 可视化组件渲染
+  - 动画与交互逻辑
+  - 响应式视觉布局
+
+---
+
+## 使用示例（待扩展）
+
+```javascript
+// 示例：实例化 Vision 组件
+const visionPanel = new bricks.Vision({
+    // 配置项（未来可扩展）
+});
+```
+
+> ⚠️ 注意：当前版本尚未实现具体方法或属性，仅提供结构骨架。
+
+---
+
+## 设计意图
+
+| 特性         | 描述 |
+|--------------|------|
+| 模块化       | 通过 `bricks` 命名空间组织代码，避免全局污染 |
+| 可扩展性     | 使用 ES6 Class 语法便于继承与多态 |
+| 职责分离     | `Vision` 专注视觉呈现，`Layout` 处理基础布局 |
+
+---
+
+## 后续开发建议
+
+1. 添加构造函数参数解析（如 `options` 对象）
+2. 实现生命周期钩子（如 `render`, `update`, `destroy`）
+3. 集成图表库（如 D3.js、ECharts 等）支持
+4. 支持响应式设计与主题定制
+
+---
+
+## 版本信息
+
+- **Bricks Framework v0.1.0**
+- **模块**：Vision（可视化模块）
+- **状态**：草案 / 初始化阶段
+
+--- 
+
+> 📝 文档更新日期：2025-04-05  
+> 更多信息请参考 [Bricks 官方文档](#)（链接待定）
\ No newline at end of file
diff --git a/aidocs/websocket.md b/aidocs/websocket.md
new file mode 100644
index 0000000..217b1fc
--- /dev/null
+++ b/aidocs/websocket.md
@@ -0,0 +1,254 @@
+# `bricks.WebSocket` 技术文档
+
+> 基于 WebSocket 的通信组件，继承自 `bricks.VBox`，用于在前端与后端之间建立双向实时通信通道。支持文本、Base64 编码的音视频数据等消息类型的发送与接收。
+
+---
+
+## 概述
+
+`bricks.WebSocket` 是一个封装了原生 WebSocket 功能的类，提供了更便捷的事件处理机制和数据封装方法。它允许开发者通过简单的配置连接到指定的 WebSocket 服务，并支持会话认证（session）以及多种类型的消息收发。
+
+该类通过 `bricks.Factory.register` 注册为可复用组件，适用于 bricks UI 框架体系。
+
+---
+
+## 继承关系
+
+- **父类**: `bricks.VBox`
+- **子类**: `bricks.WebSocket`
+
+---
+
+## 构造函数
+
+```js
+new bricks.WebSocket(options)
+```
+
+### 参数
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| `options.ws_url` | `String` | ✅ | WebSocket 服务器地址（如：`ws://localhost:8080/ws`） |
+| `options.with_session` | `Boolean` | ❌ | 是否携带当前应用会话信息进行连接，默认为 `false` |
+
+### 示例
+
+```js
+var ws = new bricks.WebSocket({
+    ws_url: 'ws://example.com/ws',
+    with_session: true
+});
+```
+
+> 当 `with_session: true` 时，系统将调用 `bricks.app.get_session()` 获取会话标识并作为协议参数传递给 WebSocket 构造函数（注意：代码中存在拼写错误 `sessopn` 应为 `session`）。
+
+---
+
+## 事件回调
+
+`bricks.WebSocket` 支持以下事件监听，可通过 `on(event, handler)` 方法绑定：
+
+| 事件名 | 触发时机 | 回调参数 |
+|--------|----------|-----------|
+| `onopen` | WebSocket 连接成功打开时 | 无 |
+| `onclose` | WebSocket 连接关闭时 | 无 |
+| `onerror` | WebSocket 发生错误时 | 错误对象 |
+| `ontext` | 接收到类型为 `text` 的消息时 | 文本数据 |
+| `onbase64audio` | 接收到 Base64 编码的音频数据时 | Base64 字符串 |
+| `onbase64video` | 接收到 Base64 编码的视频数据时 | Base64 字符串 |
+| `on{type}` | 接收到任意自定义类型 `{type}` 的消息时 | 数据体 |
+
+> 所有事件均通过 `this.dispatch(eventname, data)` 触发，可使用标准事件监听机制订阅。
+
+---
+
+## 方法说明
+
+### `on_open(e)`
+
+WebSocket 连接打开时的内部处理函数。
+
+- 触发 `onopen` 事件
+- 控制台输出 `"open"`
+
+### `on_close(e)`
+
+WebSocket 连接关闭时的内部处理函数。
+
+- 触发 `onclose` 事件
+- 控制台输出 `"close"`
+
+### `on_error(e)`
+
+WebSocket 发生错误时的内部处理函数。
+
+- 触发 `onerror` 事件
+- **⚠️ Bug 提示**：日志中 `console.log(error)` 应为 `console.log(e)`，否则会抛出未定义变量异常。
+
+### `on_message(e)`
+
+处理接收到的消息。
+
+#### 流程：
+1. 解析 `e.data` 为 JSON 对象，格式应为：
+   ```json
+   {
+     "type": "text",
+     "data": "Hello World"
+   }
+   ```
+2. 根据 `type` 动态生成事件名（如 `type: "text"` → 事件 `ontext`）
+3. 使用 `this.dispatch(eventname, d.data)` 派发事件
+
+> 支持扩展任意消息类型，只需确保服务端发送的数据结构符合规范。
+
+---
+
+### `send_text(text)`
+
+发送纯文本消息。
+
+#### 参数
+- `text` (`String`)：要发送的文本内容
+
+#### 示例
+```js
+ws.send_text("Hello from client");
+```
+
+#### 发送格式
+```json
+{ "type": "text", "data": "Hello from client" }
+```
+
+---
+
+### `send_base64_video(b64video)`
+
+发送 Base64 编码的视频数据。
+
+#### 参数
+- `b64video` (`String`)：Base64 编码的视频字符串（不含前缀如 `data:video/mp4;base64,`）
+
+#### 示例
+```js
+ws.send_base64_video(videoBase64Data);
+```
+
+#### 发送格式
+```json
+{ "type": "base64video", "data": "...base64..." }
+```
+
+---
+
+### `send_base64_audio(b64audio)`
+
+发送 Base64 编码的音频数据。
+
+#### 参数
+- `b64audio` (`String`)：Base64 编码的音频字符串
+
+#### 示例
+```js
+ws.send_base64_audio(audioBase64Data);
+```
+
+#### 发送格式
+```json
+{ "type": "base64audio", "data": "...base64..." }
+```
+
+---
+
+### `send_typedata(type, data)`
+
+发送指定类型的消息（通用接口）。
+
+#### 参数
+- `type` (`String`)：消息类型（如 `"custom"`）
+- `data` (`Any`)：任意可序列化数据
+
+#### 返回值
+- `undefined`（但调用了 `send(d)`）
+
+> **⚠️ Bug 提示**：方法体内 `return send(d);` 应为 `return this.send(d);`，否则 `send` 函数无法正确调用。
+
+---
+
+### `send(d)`
+
+底层消息发送方法，负责序列化并发送数据。
+
+#### 参数
+- `d` (`Object`)：消息对象，格式如下：
+  ```js
+  {
+    type: String,
+    data: Any
+  }
+  ```
+
+#### 行为
+1. 使用 `JSON.stringify(d)` 序列化对象
+2. 调用 `this.ws.send(s)` 发送字符串
+
+---
+
+## 已知问题 / 注意事项
+
+| 问题 | 说明 | 建议修复 |
+|------|------|---------|
+| `sessopn` 拼写错误 | `constructor` 中 `sessopn` 应为 `session` | 更正为 `this.ws = new WebSocket(this.ws_url, session);` |
+| `console.log(error)` 错误引用 | `on_error` 方法中变量名错误 | 改为 `console.log(e);` |
+| `send_typedata` 调用错误 | `send(d)` 应为 `this.send(d)` | 修正为 `return this.send(d);` |
+| 缺少连接状态管理 | 未暴露 `readyState` 或重连机制 | 可增加 `isConnected()` 方法 |
+
+---
+
+## 使用示例
+
+```js
+// 创建 WebSocket 实例
+var ws = new bricks.WebSocket({
+    ws_url: 'ws://localhost:3000/ws',
+    with_session: true
+});
+
+// 绑定事件
+ws.on('onopen', function() {
+    console.log('Connected!');
+    ws.send_text('Client ready');
+});
+
+ws.on('ontext', function(data) {
+    console.log('Received text:', data);
+});
+
+ws.on('onbase64video', function(videoData) {
+    document.getElementById('video').src = 'data:video/webm;base64,' + videoData;
+});
+```
+
+---
+
+## 注册为工厂组件
+
+```js
+bricks.Factory.register('WebSocket', bricks.WebSocket);
+```
+
+允许通过工厂模式创建实例：
+
+```js
+var instance = bricks.Factory.create('WebSocket', { ws_url: '...' });
+```
+
+---
+
+## 总结
+
+`bricks.WebSocket` 是一个轻量级、易于集成的 WebSocket 封装组件，适合用于实时通信场景（如聊天、音视频流推送、远程控制等）。尽管存在少量代码缺陷，但整体设计清晰，具备良好的扩展性和事件驱动特性。
+
+建议在实际使用前修复上述指出的问题以保证稳定性。
\ No newline at end of file
diff --git a/aidocs/webspeech.md b/aidocs/webspeech.md
new file mode 100644
index 0000000..590d3c7
--- /dev/null
+++ b/aidocs/webspeech.md
@@ -0,0 +1,240 @@
+# WebTTS 与 WebASR 模块技术文档
+
+---
+
+## 简介
+
+`bricks.WebTTS` 和 `bricks.WebASR` 是基于浏览器原生 API 实现的语音合成（Text-to-Speech, TTS）和语音识别（Automatic Speech Recognition, ASR）组件。它们扩展自 `bricks.VBox`，可用于在 Web 应用中集成语音输入与输出功能。
+
+这些模块依赖于现代浏览器提供的 `SpeechSynthesis` 和 `SpeechRecognition` API，适用于支持这些特性的主流浏览器。
+
+---
+
+## 1. `bricks.WebTTS` - 文本转语音组件
+
+### 类定义
+```js
+class bricks.WebTTS extends bricks.VBox
+```
+
+### 构造函数
+```js
+constructor(opts)
+```
+- **参数**：
+  - `opts` (Object): 传递给父类 `VBox` 的配置选项。
+- **说明**：调用父类构造函数初始化组件。
+
+### 方法：`speak(text)`
+
+触发文本到语音的合成功能。
+
+#### 参数
+| 参数名 | 类型   | 描述               |
+|--------|--------|--------------------|
+| text   | String | 要朗读的文本内容   |
+
+#### 功能描述
+- 检查当前浏览器是否支持 `speechSynthesis` API。
+- 创建一个 `SpeechSynthesisUtterance` 对象，并设置以下属性：
+  - `lang`: 使用 `bricks.app.lang` 设置语言。
+  - `pitch`: 音调设为 1（正常）。
+  - `rate`: 语速设为 1（正常）。
+- 注册事件回调：
+  - `onstart`: 语音开始播放时输出日志。
+  - `onend`: 语音结束时输出日志。
+  - `onerror`: 出错时输出错误信息。
+- 将语音任务加入系统队列并播放。
+
+#### 示例代码
+```js
+const tts = new bricks.WebTTS();
+tts.speak("你好，欢迎使用语音合成功能！");
+```
+
+#### 浏览器兼容性提示
+若浏览器不支持 `speechSynthesis`，将在控制台打印错误：
+```text
+浏览器不支持SpeechSynthesis
+```
+
+> ⚠️ 注意：该功能在部分旧版或移动浏览器上可能受限，需确保运行环境支持。
+
+---
+
+## 2. `bricks.WebASR` - 语音识别组件
+
+### 类定义
+```js
+class bricks.WebASR extends bricks.VBox
+```
+
+### 构造函数
+```js
+constructor(opts)
+```
+- **参数**：
+  - `opts` (Object): 传递给父类 `VBox` 的配置选项。
+- **内部初始化**：
+  - `this.recognition` 初始化为 `None`（注意：应为 `null` 或 `undefined`，此处可能存在拼写/语法错误）
+
+> ❌ Bug 提示：`None` 在 JavaScript 中未定义，正确写法应为 `null`。
+
+建议修正为：
+```js
+this.recognition = null;
+```
+
+### 方法：`start_recording()`
+
+启动麦克风录音并进行实时语音识别。
+
+#### 功能描述
+- 检测浏览器是否支持 `SpeechRecognition` 接口。
+- 若支持，则创建 `SpeechRecognition` 实例，并配置如下：
+  - `lang`: 使用 `bricks.app.lang` 设置识别语言。
+  - `onresult`: 当识别结果返回时，提取首个备选文本（`event.results[0][0].transcript`），并通过 `dispatch` 触发 `asr_result` 自定义事件。
+  - `onend`: 识别结束时输出日志。
+  - `onerror`: 发生错误时输出错误类型。
+- 启动识别服务。
+
+#### 示例代码
+```js
+const asr = new bricks.WebASR();
+asr.start_recording();
+
+// 监听识别结果
+asr.on('asr_result', function(data) {
+    console.log('用户说:', data.content);
+});
+```
+
+#### 控制台输出示例
+```text
+识别结果: 今天天气真好
+```
+
+#### 兼容性处理
+如果浏览器不支持 `SpeechRecognition`，将输出：
+```text
+browser has not SpeechRecognition
+```
+
+> ⚠️ 注意：Chrome 及基于 Chromium 的浏览器支持较好；Safari 和 Firefox 支持有限或需要前缀。
+
+---
+
+### 方法：`stop_recording()`
+
+停止正在进行的语音识别。
+
+#### 功能描述
+调用底层 `SpeechRecognition.stop()` 方法终止录音和识别过程。
+
+#### 示例
+```js
+asr.stop_recording();
+```
+
+> ✅ 建议配合 UI 控件（如“按住说话”按钮）使用，在释放时调用此方法。
+
+---
+
+## 3. 工厂注册
+
+这两个组件通过 `bricks.Factory` 进行注册，便于动态创建实例。
+
+```js
+bricks.Factory.register('WebTTS', bricks.WebTTS);
+bricks.Factory.register('WebASR', bricks.WebASR);
+```
+
+### 用途
+允许通过字符串名称来创建组件实例，例如（假设有工厂创建方法）：
+```js
+let tts = bricks.Factory.create('WebTTS');
+let asr = bricks.Factory.create('WebASR');
+```
+
+这提高了系统的可扩展性和解耦程度。
+
+---
+
+## 使用前提条件
+
+### 1. 浏览器支持要求
+| 特性 | 推荐浏览器 |
+|------|------------|
+| `SpeechSynthesis` | Chrome、Edge、Firefox、Safari（部分支持） |
+| `SpeechRecognition` | 主要支持 Chrome（需 HTTPS 或 localhost） |
+
+> 🔒 安全限制：大多数浏览器要求页面运行在 **HTTPS** 或本地开发环境（`localhost`）下才能启用麦克风权限。
+
+### 2. 语言设置依赖
+组件使用全局变量：
+```js
+bricks.app.lang
+```
+请确保在应用启动时正确设置该值，例如：
+```js
+bricks.app.lang = 'zh-CN'; // 中文普通话
+// 或
+bricks.app.lang = 'en-US'; // 英语（美国）
+```
+
+常见语言代码参考：
+- `zh-CN`: 中文（普通话）
+- `en-US`: 英语（美式）
+- `ja-JP`: 日语
+- `ko-KR`: 韩语
+
+---
+
+## 已知问题与改进建议
+
+| 问题 | 说明 | 建议修复 |
+|------|------|---------|
+| `None` 错误 | `this.reognition = None;` 是无效语法 | 改为 `this.recognition = null;` |
+| 拼写错误 | `reognition` → `recognition` | 修正所有相关拼写 |
+| 缺少权限请求处理 | 未显式请求麦克风权限 | 可增加 `navigator.mediaDevices.getUserMedia` 预检 |
+| 事件作用域问题 | `onresult` 中 `this` 指向可能丢失 | 使用箭头函数或 `.bind(this)` |
+
+### 推荐修复后的 `start_recording` 片段
+```js
+this.recognition.onresult = (event) => {
+    const transcript = event.results[0][0].transcript;
+    this.dispatch('asr_result', { content: transcript });
+    console.log('识别结果:', transcript);
+};
+```
+
+---
+
+## 总结
+
+| 组件       | 功能             | 核心 API                  | 是否需要网络 | 是否需要麦克风 |
+|------------|------------------|----------------------------|--------------|----------------|
+| `WebTTS`   | 文本转语音       | `SpeechSynthesis`          | 否           | 否             |
+| `WebASR`   | 语音转文本       | `SpeechRecognition`        | 是（云端）   | 是             |
+
+✅ 适用场景：
+- 教育类应用中的发音朗读
+- 智能助手对话界面
+- 无障碍访问工具
+- 语音指令控制系统
+
+🚫 不适用场景：
+- 无网络环境下离线高精度 ASR
+- 低延迟工业级语音处理
+
+---
+
+## 参考链接
+
+- [MDN: SpeechSynthesis](https://developer.mozilla.org/zh-CN/docs/Web/API/SpeechSynthesis)
+- [MDN: SpeechRecognition](https://developer.mozilla.org/zh-CN/docs/Web/API/SpeechRecognition)
+- [Google Chrome 语音识别限制说明](https://www.chromium.org/developers/design-documents/media/capture)
+
+--- 
+
+📝 **维护建议**：定期检查浏览器对 Web Speech API 的支持情况，并考虑降级方案（如接入第三方 SDK）。
\ No newline at end of file
diff --git a/aidocs/widget.md b/aidocs/widget.md
new file mode 100644
index 0000000..ae383f8
--- /dev/null
+++ b/aidocs/widget.md
@@ -0,0 +1,499 @@
+以下是为提供的 JavaScript 代码编写的 **Markdown 格式技术文档**，涵盖了核心类结构、继承关系、属性、方法和使用说明。
+
+---
+
+# Bricks UI 组件库技术文档
+
+`bricks.JsWidget` 是 Bricks 框架中的基础 UI 组件类，提供通用的 DOM 管理、样式设置、事件绑定、弹窗支持等功能。其他文本类组件（如 `Text`, `Title`, `Tooltip` 等）均继承自该基类或其子类。
+
+---
+
+## 目录
+
+- [1. 基础结构](#1-基础结构)
+- [2. `JsWidget` 类](#2-jswidget-类)
+  - [构造函数](#构造函数)
+  - [实例属性](#实例属性)
+  - [公共方法](#公共方法)
+    - [DOM 操作](#dom-操作)
+    - [样式与 CSS](#样式与-css)
+    - [事件处理](#事件处理)
+    - [尺寸与布局](#尺寸与布局)
+    - [弹窗功能](#弹窗功能)
+    - [全屏控制](#全屏控制)
+    - [显示/隐藏控制](#显示隐藏控制)
+    - [ID 与属性管理](#id-与属性管理)
+- [3. `TextBase` 类](#3-textbase-类)
+- [4. 文本组件系列](#4-文本组件系列)
+  - [`Text`](#text)
+  - [`KeyinText`](#keyintext)
+  - [`Title1` ~ `Title6`](#title1--title6)
+- [5. Tooltip 组件](#5-tooltip-组件)
+- [6. 工厂注册](#6-工厂注册)
+- [7. 使用示例](#7-使用示例)
+
+---
+
+## 1. 基础结构
+
+```js
+var bricks = window.bricks || {};
+```
+
+确保 `bricks` 全局命名空间存在，并在此基础上定义各类组件。
+
+所有组件以 ES6 Class 形式实现，支持继承和模块化扩展。
+
+---
+
+## 2. `JsWidget` 类
+
+> 基础 UI 组件类，封装了 DOM 创建、样式设置、事件监听、动态尺寸调整等通用能力。
+
+### 构造函数
+
+```js
+constructor(options)
+```
+
+#### 参数：
+| 参数名 | 类型 | 说明 |
+|-------|------|------|
+| `options` | Object | 配置选项对象，可选 |
+
+#### 支持的配置项：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `baseURI` | String | 基础资源路径 |
+| `css` | String | 添加到元素的 CSS 类名（空格分隔） |
+| `csses` | String | 同 `css`，兼容旧写法 |
+| `tip` | String | 鼠标悬停提示文字（自动绑定 tooltip） |
+| `popup` | Object | 弹窗配置对象 |
+| &nbsp;&nbsp;`.popup_event` | String | 触发弹窗的事件类型（如 `'click'`） |
+| &nbsp;&nbsp;`.popup_desc` | WidgetDesc | 弹窗内容描述（用于构建内部组件） |
+| &nbsp;&nbsp;`.popupwindow` | Boolean | 是否使用独立窗口模式弹窗 |
+| &nbsp;&nbsp;`.options` | Object | 传递给 Popup/PoupWindow 的参数 |
+| `bgimage` | String (URL) | 背景图片 URL |
+| `width`, `height` | String/Number | 宽高（支持像素或字符串如 `'100%'`） |
+| `x`, `y` | Number | X/Y 偏移（暂未实际定位） |
+| `dynsize` | Boolean | 启用字符单位动态缩放 |
+| `cwidth`, `cheight` | Number | 字符宽度/高度单位（乘以 `charsize` 得到真实 px） |
+| `cfontsize` | Number | 字体大小（相对于字符单位） |
+| `color`, `bgcolor` | String | 文字颜色 / 背景色（`bgcolor` 映射为 `backgroundColor`） |
+| `align`, `textAlign` | String | 对齐方式 |
+| `margin`, `padding` 等 | Any | 支持多种标准 CSS 属性直接传入 |
+
+> ⚠️ 注意：`opts_set_style()` 方法会将匹配的 `options` 键自动映射到 DOM 样式上。
+
+---
+
+### 实例属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `dom_element` | HTMLElement | 关联的 DOM 元素（默认为 `<div>`） |
+| `id` | String | 自动生成的唯一 ID（通过 `bricks.uuid()`） |
+| `baseURI` | String | 当前组件的基础 URI |
+| `opts` | Object | 传入的原始配置对象 |
+| `parent` | JsWidget | 父级组件（尚未在代码中赋值） |
+| `_container` | Boolean | 是否为容器组件（默认 `false`） |
+| `sizable_elements` | Array | 参与字体缩放的子元素列表 |
+| `user_data` | Any | 用户自定义数据存储 |
+| `popup_widget` | Popup \| PopupWindow | 当前打开的弹窗实例（延迟创建） |
+
+---
+
+### 公共方法
+
+#### DOM 操作
+
+##### `.create()`
+创建一个 `<div>` 作为根元素并赋值给 `this.dom_element`。
+
+##### `.is_in_dom() → Boolean`
+检查当前组件是否已插入文档树中。
+
+##### `.showRectage() → DOMRect`
+返回组件的边界矩形（调用 `getBoundingClientRect()`）。
+
+---
+
+#### 样式与 CSS
+
+##### `.set_style(key, value)`
+设置单个 CSS 样式属性。
+
+```js
+widget.set_style('color', 'red');
+```
+
+##### `.set_css(css, remove_flg)`
+添加或移除 CSS 类名（支持多个类名空格分隔）。
+
+```js
+widget.set_css('btn primary');        // 添加类
+widget.set_css('hidden', true);       // 移除类
+```
+
+##### `.set_csses(csses, remove_flg)`
+同 `.set_css()`，保留向后兼容。
+
+##### `.unset_css(css)`
+移除指定 CSS 类。
+
+##### `.set_cssObject(cssobj)`
+批量设置内联样式对象（通过 `bricks.extend` 扩展）。
+
+##### `.opts_set_style()`
+根据 `options` 中的键值自动设置对应样式，支持别名映射（如 `bgcolor → backgroundColor`），并处理 `cwidth`/`cheight` 字符单位转换。
+
+##### `.charsize_sizing()`
+响应全局 `charsize` 变化的回调函数，重新计算基于字符单位的宽高和字体大小。
+
+> 自动绑定于 `dynsize: true` 时。
+
+##### `.set_bg_image(url)`
+设置背景图，应用以下样式：
+- `background-size: cover`
+- `background-position: center`
+- `background-repeat: no-repeat`
+
+---
+
+#### 事件处理
+
+##### `.bind(eventname, handler)`
+绑定 DOM 事件。
+
+```js
+widget.bind('click', () => console.log('clicked'));
+```
+
+##### `.unbind(eventname, handler)`
+解绑事件。
+
+##### `.dispatch(eventname, params)`
+派发自定义事件，携带 `params` 数据。
+
+```js
+widget.dispatch('changed', { data: 'new value' });
+```
+
+> 注：`params` 会挂载在事件对象的 `.params` 属性上。
+
+---
+
+#### 尺寸与布局
+
+##### `.get_width() → Number`
+返回客户端宽度（`clientWidth`）。
+
+##### `.get_height() → Number`
+返回客户端高度（`clientHeight`）。
+
+##### `.set_width(width)`
+设置宽度，若传入数字则自动加 `'px'`。
+
+##### `.set_height(height)`
+同上，设置高度。
+
+##### `.h_center()`, `.h_left()`, `.h_right()`
+水平对齐：
+- `h_center`: `margin: auto`
+- `h_left`: `marginLeft: 0`
+- `h_right`: `marginRight: 0`
+
+##### `.ht_center()`, `.ht_left()`, `.ht_right()`
+文本对齐：
+- 设置 `textAlign` 样式。
+
+---
+
+#### 弹窗功能
+
+##### `.popup_action() → Promise<void>`
+异步处理弹窗显示/关闭逻辑：
+- 若已有弹窗，则销毁；
+- 否则根据 `popup.popupwindow` 决定创建 `PopupWindow` 或 `Popup`；
+- 使用 `bricks.widgetBuild(popup_desc, parent, userData)` 动态构建内容；
+- 显示并定位弹窗。
+
+##### `.destroy_popup()`
+销毁当前弹窗实例，清空引用。
+
+> 绑定在弹窗的 `'dismissed'` 事件上。
+
+> 💡 提示：`popup_desc` 应符合框架的组件描述格式。
+
+---
+
+#### 全屏控制
+
+##### `.enter_fullscreen()`
+请求进入全屏模式，兼容各浏览器 API（Fullscreen API）。
+
+##### `.exit_fullscreen()`
+退出全屏模式（调用 `document.exitFullscreen()`）。
+
+---
+
+#### 显示/隐藏控制
+
+##### `.show()`
+显示组件（`display = ''`）。
+
+##### `.hide()`
+隐藏组件（`display = 'none'`）。
+
+##### `.toggle_hide()`
+切换显隐状态。
+
+##### `.is_hide() → Boolean`
+判断是否处于隐藏状态。
+
+---
+
+#### ID 与属性管理
+
+##### `.set_id(id)`
+设置组件 ID，并同步到 DOM。
+
+##### `.set_baseURI(uri)`
+更新 `baseURI`，若为容器则递归通知子组件更新。
+
+##### `.set_attribute(attr, value)`
+设置 DOM 属性。
+
+##### `.get_attribute(attr) → String`
+获取 DOM 属性（⚠️ 当前实现有误，缺少 `return`）。
+
+> ❌ 修正建议：
+```js
+get_attribute(attr) {
+  return this.dom_element.getAttribute(attr);
+}
+```
+
+##### `.selected(flag)`
+添加或移除 `selected` CSS 类。
+
+---
+
+#### 辅助方法
+
+##### `.observable(name, value)`
+创建一个可观察对象（绑定到当前组件），用于响应式数据管理。
+
+##### `.disabled(flag)`
+启用/禁用交互（通过 `pointerEvents: none/auto` 控制）。
+
+##### `.getUserData() → Any`
+获取用户数据。
+
+##### `.setUserData(v)`
+设置用户数据。
+
+---
+
+## 3. `TextBase` 类
+
+> 文本组件基类，继承自 `JsWidget`，支持国际化（i18n）、文本渲染、字体缩放。
+
+### 构造函数
+
+```js
+constructor(options)
+```
+
+#### 特有配置项：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `text` | String | 初始文本内容 |
+| `otext` | String | 原始文本（用于 i18n 查找） |
+| `i18n` | Boolean | 是否启用国际化 |
+| `rate` | Number | 字体缩放系数（默认 1） |
+| `halign`, `valign` | String | 水平/垂直对齐（未在代码中使用） |
+| `color`, `bgtcolor` | String | 文字/背景色（后者未使用） |
+
+### 方法
+
+##### `.set_attrs()`
+初始化文本内容：
+- 优先使用 `text`
+- 若提供 `otext` 和 `i18n`，则通过 `I18n._()` 转换
+- 设置 `innerHTML`
+
+##### `.set_text(text)`
+更新文本内容（同时更新 `this.text` 和 DOM）。
+
+##### `.set_otext(otxt)`
+更新原始文本，并重新国际化渲染。
+
+##### `.set_i18n_text()`
+触发国际化文本刷新（通常由语言变更事件驱动）。
+
+---
+
+## 4. 文本组件系列
+
+### `Text`
+
+> 普通文本组件，字体大小为 `1 × charsize`。
+
+```js
+new bricks.Text({ text: "Hello" })
+```
+
+- 继承 `TextBase`
+- 默认 `cfontsize = 1`
+- 自动调用 `charsize_sizing()`
+
+---
+
+### `KeyinText`
+
+> 可输入文本组件，模拟键盘输入行为。
+
+#### 功能：
+- 监听全局 `keydown` 事件（绑定至 `bricks.app`）
+- 支持：
+  - 输入单字符
+  - Backspace 删除末尾字符
+  - Delete 清空内容
+- 每次变更后派发 `changed` 事件，携带 `{ name: text }` 数据
+- 默认 `name = 'data'`
+
+#### 方法：
+- `dispatch_changed()`：封装事件派发逻辑
+
+> 📝 示例用途：简易输入框、密码输入、命令行模拟。
+
+---
+
+### `Title1` ~ `Title6`
+
+> 六级标题组件，字体加粗，字号逐级递减。
+
+| 组件 | `cfontsize` |
+|------|------------|
+| `Title1` | 1.96 |
+| `Title2` | 1.80 |
+| `Title3` | 1.64 |
+| `Title4` | 1.48 |
+| `Title5` | 1.32 |
+| `Title6` | 1.16 |
+
+均设置 `fontWeight: bold`，并自动适配字符尺寸。
+
+---
+
+## 5. Tooltip 组件
+
+> 工具提示组件，继承自 `Text`，预设样式。
+
+### 构造选项
+- `rate: 0.8`：较小字体
+- `tip: null`：避免递归绑定提示
+- 添加 `modal` CSS 类
+- 最小宽度 `90px`
+- 自动隐藏任务调度器（`auto_task`）
+
+### 方法
+
+##### `.show(otext, event)`
+显示提示框：
+- 设置文本
+- 设为可见且高 `zIndex`
+- 定位到鼠标事件位置（`bricks.relocate_by_eventpos`）
+- 启动 6 秒后自动隐藏（可取消）
+
+##### `.hide()`
+隐藏提示框，清除定时任务。
+
+> ✅ 支持防抖和重复触发清理。
+
+---
+
+## 6. 工厂注册
+
+所有组件通过 `bricks.Factory.register` 注册，便于动态创建：
+
+```js
+bricks.Factory.register('Tooltip', bricks.Tooltip);
+bricks.Factory.register('Text', bricks.Text);
+// ... 其他组件
+```
+
+支持通过名称字符串动态实例化组件。
+
+---
+
+## 7. 使用示例
+
+### 创建普通文本
+```js
+const text = new bricks.Text({
+  text: 'Welcome!',
+  css: 'text-primary bold',
+  width: 200,
+  tip: 'This is a welcome message'
+});
+document.body.appendChild(text.dom_element);
+```
+
+### 创建可输入文本
+```js
+const input = new bricks.KeyinText({
+  name: 'username',
+  cwidth: 20
+});
+input.bind('changed', e => {
+  console.log('Input changed:', e.params);
+});
+```
+
+### 创建标题
+```js
+const title = new bricks.Title1({
+  otext: 'Main Title',
+  i18n: true
+});
+```
+
+### 创建带弹窗的按钮（假设）
+```js
+const btn = new bricks.Text({
+  text: 'Click Me',
+  popup: {
+    popup_event: 'click',
+    popup_desc: { type: 'Panel', children: [...] },
+    popupwindow: false
+  }
+});
+```
+
+### 设置背景图
+```js
+widget.set_bg_image('/images/bg.jpg');
+```
+
+---
+
+## 总结
+
+`bricks.JsWidget` 提供了一个灵活、可扩展的前端组件基类，具备以下优势：
+
+✅ 模块化设计  
+✅ 支持动态尺寸（字符单位）  
+✅ 内建弹窗、tooltip、国际化支持  
+✅ 易于继承和定制  
+✅ 与 Bricks 框架深度集成（event bus, factory, resize observer）
+
+适用于构建响应式、多语言、高交互性的 Web 应用界面。
+
+--- 
+
+> 📚 *文档版本：v1.0*  
+> © 2025 Bricks Framework Team
\ No newline at end of file
diff --git a/aidocs/wsllm.md b/aidocs/wsllm.md
new file mode 100644
index 0000000..2b24ac1
--- /dev/null
+++ b/aidocs/wsllm.md
@@ -0,0 +1,427 @@
+# `bricks.LlmIO` 技术文档
+
+> 本模块实现了一个基于 Web 的多模型 LLM（大语言模型）交互界面组件，支持流式/同步响应、用户输入、语音输出、反馈评分等功能。适用于构建类 ChatGPT 的对话系统。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [核心类结构](#核心类结构)
+- [类详解](#类详解)
+  - [`bricks.LlmIO`](#bricksllmio)
+  - [`bricks.LlmModel`](#bricksllmmodel)
+  - [`bricks.ModelOutput`](#bricksmodeloutput)
+  - [`bricks.RoleOutput`](#bricksroleoutput)
+- [数据格式说明](#数据格式说明)
+- [事件与回调机制](#事件与回调机制)
+- [扩展功能](#扩展功能)
+- [使用示例](#使用示例)
+- [依赖与注册](#依赖与注册)
+
+---
+
+## 概述
+
+`bricks.LlmIO` 是一个复合型 UI 控件，用于集成多个 LLM 模型并统一管理用户输入和模型输出。它提供了以下能力：
+
+- 支持添加多个 LLM 模型；
+- 用户通过表单提交输入；
+- 支持 **流式 (stream)**、**同步 (sync)** 和 **异步 (async)** 响应模式；
+- 输出内容可动态渲染（支持模板化视图）；
+- 支持 TTS（文本转语音）流式播放；
+- 可对模型输出进行满意度评分（点赞/踩）；
+- 自动维护会话历史（可选）；
+
+该组件基于 `bricks.js` 框架构建，采用面向对象设计，高度可配置和可扩展。
+
+---
+
+## 核心类结构
+
+| 类名 | 功能 |
+|------|------|
+| `bricks.LlmIO` | 主容器，管理所有模型实例和输入/输出区域 |
+| `bricks.LlmModel` | 单个 LLM 模型的封装，处理请求发送与消息管理 |
+| `bricks.ModelOutput` | 显示单条模型输出结果，支持富内容渲染与反馈控件 |
+| `bricks.RoleOutput` *(内部基类)* | 统一用户与模型输出样式布局的基础类 |
+
+---
+
+## 类详解
+
+### `bricks.LlmIO`
+
+主控件，继承自 `bricks.VBox`，作为整个对话系统的容器。
+
+#### 构造参数 (`opts`)
+
+```js
+{
+  ws_url: String,               // WebSocket 地址（预留未使用）
+  user_icon: String,            // 用户头像图标 URL
+  list_models_url: String,      // 获取可用模型列表的 API 接口
+  input_fields: Array,          // 输入表单字段定义（用于 bricks.Form）
+  input_view: Object,           // 定义如何展示用户输入的内容（widget 描述）
+  output_view: Object,          // 默认全局输出视图模板（可被模型覆盖）
+  models: Array<LlmModelOpts>,  // 初始加载的模型配置数组
+  tts_url: String,              // TTS 接口地址（启用语音时使用）
+  estimate_url: String,         // 提交反馈评分的接口地址
+  msg_css: String               // 用户消息的 CSS 类名（默认 'user_msg'）
+}
+```
+
+#### 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `ws` | `bricks.WebSocket` | 预留 WebSocket 实例（当前未实际使用） |
+| `llmmodels` | `Array<bricks.LlmModel>` | 已添加的模型实例列表 |
+| `title_w` | `bricks.HBox` | 顶部显示模型标签的容器 |
+| `o_w` | `bricks.Filler` | 输出内容滚动区域 |
+| `i_w`, `nm_w` | `bricks.Svg` | “输入” 和 “新增模型” 图标按钮 |
+| `textvoice` | Boolean | 是否启用文本语音合成功能 |
+
+#### 方法
+
+##### `constructor(opts)`
+初始化主界面，创建标题栏、输出区、底部操作按钮，并加载初始模型。
+
+##### `show_added_model(m)`
+将给定模型配置 `m` 实例化为 `LlmModel` 并加入界面。
+
+- 若启用了 `textvoice`，自动注入 TTS 配置。
+- 调用 `render_title()` 创建模型标签并插入标题栏。
+
+##### `open_search_models(event)`
+弹出模型选择弹窗（`PopupWindow`），从服务器拉取可选模型列表。
+
+- 使用 `bricks.Cols` 展示模型卡片列表；
+- 点击任一模型触发 `add_new_model()`；
+- 弹窗点击后自动关闭。
+
+##### `add_new_model(event)`
+接收来自 `Cols` 的选中模型数据，将其加入 `this.models` 数组，并调用 `show_added_model()` 渲染到界面上。
+
+##### `open_input_widget(event)`
+打开输入表单弹窗，允许用户输入内容。
+
+- 使用 `bricks.Form` 构建表单；
+- 表单字段由 `input_fields` 配置；
+- 提交后触发 `handle_input()`。
+
+##### `handle_input(event)`
+处理用户输入数据：
+
+1. 调用 `show_input(params)` 显示用户输入；
+2. 遍历所有 `LlmModel` 实例，若其接受 `'userinput'` 来源，则调用 `model_inputed(params)` 发起请求。
+
+> 使用 `schedule_once` 延迟执行以避免阻塞 UI。
+
+##### `show_input(params)`
+将用户输入数据根据 `input_view` 模板渲染成可视化组件，并显示在输出区域左侧（带用户图标）。
+
+- 支持富文本或结构化数据显示；
+- 添加 CSS 类 `user_msg` 或自定义类名。
+
+---
+
+### `bricks.LlmModel`
+
+表示一个具体的 LLM 模型实例，负责请求发送、消息管理和响应解析。
+
+#### 构造参数 (`opts`)
+
+```js
+{
+  icon: String,
+  model: String,                  // 模型名称
+  url: String,                    // 请求后端 API 地址
+  output_view: Object|String,     // 输出渲染模板（widget 描述）
+  params: Object,                 // 固定请求参数
+  user_message_format: Object,    // 用户消息格式模板
+  system_message_format: Object,  // 系统消息格式模板
+  llm_message_format: Object,     // 模型回复消息格式模板
+  use_session: Boolean,           // 是否保持会话上下文
+  input_from: String,             // 接收输入来源标识（如 'userinput'）
+  textvoice: Boolean,             // 是否启用 TTS
+  tts_url: String,                // TTS 流地址
+  response_mode: 'stream'|'sync'|'async'  // 响应模式
+}
+```
+
+#### 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `llmio` | `bricks.LlmIO` | 所属父容器 |
+| `messages` | Array | 当前会话的历史消息（遵循 OpenAI 类似格式） |
+| `resp_data` | Object | 最终完整响应数据（用于 sync 模式拼接） |
+
+#### 方法
+
+##### `constructor(llmio, opts)`
+初始化模型实例，设置默认消息格式。
+
+##### `render_title()`
+生成模型标题栏组件（HBox），包含图标和点击事件绑定（未来可用于配置面板）。
+
+##### `inputdata2uploaddata(data)`
+将原始输入数据转换为适合发送给后端的格式：
+
+- 支持 `FormData` 或普通对象；
+- 自动追加 `model`, `modelinstanceid`, `modeltypeid`, `messages` 等字段；
+- 若定义了 `user_message_format`，则按模板格式化用户消息并推入 `messages`。
+
+##### `model_inputed(data)`
+主入口方法：当收到用户输入时触发。
+
+根据 `response_mode` 分支处理：
+
+| 模式 | 处理方式 |
+|------|---------|
+| `stream` / `async` | 使用 `HttpResponseStream` 分块接收流式响应，逐段更新输出 |
+| `sync` | 使用 `HttpJson` 一次性获取完整响应，并整体更新 |
+
+> 在流式模式下，每收到一段数据都会调用 `chunk_response()` 更新 UI。
+
+##### `is_accept_source(source)`
+判断是否接受指定来源的输入（目前仅支持 `'userinput'`）。
+
+##### `llm_msg_format()`
+返回模型回复消息的标准格式，默认为：
+```json
+{ "role": "assistant", "content": "${content}" }
+```
+
+##### `chunk_response(mout, line)`
+处理流式响应中的每一个数据块：
+
+- 解析 JSON；
+- 过滤空内容；
+- 转义特殊字符；
+- 调用 `mout.update_data(d)` 实时更新输出；
+- 累积内容至 `this.resp_data`。
+
+##### `chunk_ended()`
+流式响应结束后，将最终累积的内容按 `llm_msg_format` 格式化并压入 `messages` 数组，完成上下文保存。
+
+---
+
+### `bricks.ModelOutput`
+
+继承自 `RoleOutput`，专门用于显示 **LLM 模型的输出内容**。
+
+#### 构造参数 (`opts`)
+
+```js
+{
+  icon: String,
+  model: String,
+  estimate_url: String,       // 提交评分的接口地址
+  output_view: Object|String, // 输出内容渲染模板
+  textvoice: Boolean,
+  tts_url: String
+}
+```
+
+#### 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `img` | `bricks.Svg` | 模型图标 |
+| `filler` | `bricks.VBox` | 内容填充区域 |
+| `run` | `bricks.BaseRunning` | 加载动画（请求中状态） |
+| `estimate_w` | `bricks.HBox` | 满意度评价组件（点赞/踩） |
+| `upstreaming` | `bricks.UpStreaming` | TTS 流上传器（语音播报） |
+| `logid` | String | 日志 ID（用于反馈关联） |
+
+#### 方法
+
+##### `constructor(opts)`
+初始化输出框：
+
+- 创建头部模型信息行（图标 + 名称）；
+- 创建内容区域（含加载动画）；
+- 若是 LLM 角色，创建左右留白；
+- 调用 `build_estimate_widgets()` 创建评价控件（如果配置了 `estimate_url`）。
+
+##### `build_estimate_widgets()`
+构建“结果满意吗？”评价组件：
+
+- 包含文字提示、“赞”和“踩”SVG图标；
+- 绑定点击事件到 `estimate_llm(val)`；
+- 初始隐藏，待有 `logid` 时再显示。
+
+##### `estimate_llm(val, event)`
+提交用户评分：
+
+- 构造 `urlwidget` 请求描述；
+- 参数包括 `logid` 和评分值（1=满意，-1=不满意）；
+- 动态创建 widget 发起请求；
+- 提交后禁用按钮防止重复提交。
+
+##### `update_data(data)`
+更新输出内容：
+
+- 移除加载动画；
+- 启动 TTS 流（如有配置）；
+- 使用 `output_view` 模板结合 `data` 数据构建 UI 组件；
+- 将组件添加到 `filler` 中；
+- 若存在 `logid`，显示评价组件。
+
+> 支持 `output_view` 为字符串（JSON 字符串）或对象。
+
+##### `finish()`
+结束 TTS 流传输。
+
+---
+
+### `bricks.RoleOutput`
+
+> ⚠️ 注意：代码中存在语法错误 —— `defautl_icon` 应为 `default_icon`
+
+`ModelOutput` 的基类，也用于用户输出（但未导出独立类）。统一管理角色输出的布局结构。
+
+#### 共享特性
+
+- 左侧图标（用户 or LLM）；
+- 内容区域居中对齐；
+- 左右两侧空白图标占位（实现对话气泡错位效果）；
+- 支持动态内容更新。
+
+---
+
+## 数据格式说明
+
+### `output_view` 结构
+
+用于定义模型输出的 UI 渲染模板，是一个标准的 `bricks.widget` 描述对象：
+
+```js
+{
+  widgettype: "Text",
+  options: {
+    text: "${content}",
+    wrap: true
+  }
+}
+```
+
+支持变量插值（`${xxx}`），由 `bricks.apply_data(template, data)` 替换。
+
+### `input_view` 结构
+
+同上，用于渲染用户输入内容。
+
+### 消息格式（`messages` 数组项）
+
+```js
+{
+  role: 'user' | 'system' | 'assistant',
+  content: String
+}
+```
+
+可通过 `user_message_format`、`llm_message_format` 自定义格式。
+
+---
+
+## 事件与回调机制
+
+| 事件名 | 触发条件 | 示例 |
+|--------|----------|------|
+| `record_click` | Cols 中某条记录被点击 | 添加新模型 |
+| `submit` | Form 提交 | 处理用户输入 |
+| `click` | SVG 按钮点击 | 打开输入窗、添加模型 |
+| 自定义绑定 | 如 `likew.bind('click', ...)` | 提交评分 |
+
+---
+
+## 扩展功能
+
+### ✅ 流式响应支持
+通过 `HttpResponseStream` 实现 SSE 或分块传输解码，实时更新输出。
+
+### ✅ 文本转语音（TTS）
+利用 `UpStreaming` 组件边生成边播放音频流，提升交互体验。
+
+### ✅ 用户反馈评分
+提供“点赞/踩”按钮，收集用户对模型输出质量的反馈。
+
+### ✅ 多模型共存
+支持同时运行多个模型，各自独立维护上下文。
+
+### ✅ 模板化渲染
+使用 `apply_data()` 实现数据驱动的 UI 渲染，灵活支持 Markdown、代码块等复杂内容。
+
+---
+
+## 使用示例
+
+```js
+var llmio = new bricks.LlmIO({
+  user_icon: '/icons/user.png',
+  list_models_url: '/api/models/list',
+  input_fields: [
+    { name: 'prompt', type: 'textarea', label: '请输入问题' }
+  ],
+  input_view: {
+    widgettype: 'Text',
+    options: { text: '${prompt}', css: 'user-input' }
+  },
+  estimate_url: '/api/feedback/rate',
+  tts_url: '/api/tts/stream',
+  models: [{
+    model: 'gpt-3.5-turbo',
+    icon: '/icons/gpt.svg',
+    url: '/api/llm/chat',
+    output_view: {
+      widgettype: 'Markdown',
+      options: { source: '${content}' }
+    },
+    response_mode: 'stream',
+    input_from: 'userinput',
+    use_session: true
+  }]
+});
+
+document.body.appendChild(llmio.dom);
+```
+
+---
+
+## 依赖与注册
+
+```js
+bricks.Factory.register('LlmIO', bricks.LlmIO);
+```
+
+确保该组件可通过工厂方式动态创建：
+
+```js
+bricks.widgetBuild({ widgettype: 'LlmIO', options: {...} });
+```
+
+---
+
+## 已知问题与改进建议
+
+| 问题 | 建议修复 |
+|------|---------|
+| `defautl_icon` 拼写错误 → 应为 `default_icon` | 修正拼写 |
+| `opts` 在 `model_inputed` 中引用错误（应为 `this.opts`） | 修改为 `this.opts.use_session` |
+| `ws` 成员未实际使用 | 删除或补充 WebSocket 支持逻辑 |
+| `handle_input` 中注释掉 `await` 可能导致并发问题 | 建议保留 `await` 或明确使用异步调度 |
+
+---
+
+## 版本信息
+
+- 编写日期：2025年4月
+- 框架版本：`bricks.js` （假设）
+- 作者：Auto-generated from source code
+
+--- 
+
+✅ **文档完**
\ No newline at end of file
diff --git a/aidocs/wterm.md b/aidocs/wterm.md
new file mode 100644
index 0000000..c7ae0cd
--- /dev/null
+++ b/aidocs/wterm.md
@@ -0,0 +1,347 @@
+# `bricks.Wterm` 技术文档
+
+> 基于 xterm.js 的终端组件，通过 WebSocket 与后端交互，支持自动连接、心跳保活、终端尺寸自适应等功能。
+
+---
+
+## 概述
+
+`bricks.Wterm` 是一个基于 [xterm.js](https://xtermjs.org/) 的前端终端控件类，继承自 `bricks.JsWidget`。它用于在网页中嵌入一个可交互的终端界面，并通过 WebSocket 连接到后端服务进行数据通信。
+
+该组件主要功能包括：
+
+- 终端渲染（使用 xterm.js）
+- WebSocket 通信管理
+- 自动发送终端尺寸
+- 心跳机制保活连接
+- 键盘输入转发
+- DOM 生命周期绑定（如页面显示/隐藏时自动处理连接）
+
+---
+
+## 依赖
+
+- **xterm.js**：核心终端库
+- **FitAddon for xterm.js**：用于自适应容器大小
+- `bricks.js` 框架运行环境
+- 全局函数 `schedule_once(fn, delay)`：用于延迟执行任务（类似 `setTimeout` 封装）
+
+---
+
+## 类定义
+
+```js
+class bricks.Wterm extends bricks.JsWidget
+```
+
+---
+
+## 构造函数
+
+### `constructor(opts)`
+
+初始化终端组件。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `opts.ws_url` | `String` | WebSocket 服务器地址（必需） |
+| `opts.ping_timeout` | `Number` | 心跳间隔时间（秒），默认为 `19` 秒 |
+
+#### 示例
+
+```js
+const term = new bricks.Wterm({
+  ws_url: 'ws://localhost:8080/ws',
+  ping_timeout: 20
+});
+```
+
+#### 内部逻辑
+
+1. 调用父类构造函数。
+2. 初始化 `socket` 为 `null`。
+3. 设置心跳超时时间。
+4. 使用 `schedule_once` 延迟调用 `open()` 方法（避免同步阻塞）。
+5. 绑定事件：
+   - `'domon'` → 当元素可见时触发 `send_term_size`
+   - `'domoff'` → 当元素不可见时触发 `destroy`
+
+---
+
+## 核心方法
+
+### `async open()`
+
+建立终端和 WebSocket 连接。
+
+#### 流程说明
+
+1. 创建 `Terminal` 实例并应用配置（包括宽高百分比等）。
+2. 将终端挂载到 `this.dom_element`（由父类提供）。
+3. 创建 WebSocket 连接至 `opts.ws_url`。
+4. 加载 `FitAddon` 插件以实现自适应布局。
+5. 调整字体大小（依赖全局 `bricks.app.charsize`）。
+6. 设置 WebSocket 回调：
+   - `onmessage`：接收服务器数据并写入终端
+   - `onclose`：清理心跳任务
+   - `onopen`：连接成功后发送初始尺寸并启动心跳
+7. 监听键盘输入，转发至服务端。
+8. 监听终端尺寸变化，自动同步。
+9. 主动发送一次终端尺寸并聚焦。
+
+#### 接收消息类型（来自服务端）
+
+| 类型 | 数据结构 | 动作 |
+|------|----------|------|
+| `"heartbeat"` | `{ data: { type: "heartbeat" } }` | 打印日志：“connection alive” |
+| `"data"` | `{ data: { type: "data", data: "..." } }` | 调用 `term.write(...)` 显示内容 |
+| 其他 | 任意 | 打印原始消息内容 |
+
+#### 发送消息类型（至服务端）
+
+| 类型 | 数据格式 | 触发条件 |
+|------|---------|----------|
+| `"input"` | `{ type: "input", data: key }` | 用户按键输入 |
+| `"resize"` | `{ type: "resize", width, height, rows, cols }` | 终端或窗口尺寸改变 |
+| `"heartbeat"` | `{ type: "heartbeat" }` | 定期发送心跳 |
+
+---
+
+### `send_data(d)`
+
+向服务器发送用户输入的数据。
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `d` | `String` | 键盘输入字符 |
+
+#### 示例
+
+```js
+this.send_data('hello');
+```
+
+#### 实现
+
+```js
+this.socket.send(JSON.stringify({ type: "input", data: d }));
+```
+
+---
+
+### `send_term_size()`
+
+向服务器发送当前终端的尺寸信息。
+
+#### 发送内容
+
+```json
+{
+  "type": "resize",
+  "width": <容器宽度>,
+  "height": <容器高度>,
+  "rows": <行数>,
+  "cols": <列数>
+}
+```
+
+#### 注意事项
+
+- 若 WebSocket 尚未就绪（`readyState !== 1`），会捕获异常并打印 `'ws not ready'`。
+- 在 `open()` 中被调用两次：首次连接 + 终端初始化后。
+
+---
+
+### `send_heartbeat()`
+
+发送心跳包以维持连接活跃。
+
+#### 发送内容
+
+```json
+{ "type": "heartbeat" }
+```
+
+---
+
+### `heartbeat()`
+
+周期性执行的心跳函数。
+
+#### 行为逻辑
+
+1. 检查 WebSocket 是否处于打开状态（`readyState === 1`）。
+2. 如果是，则调用 `send_heartbeat()`。
+3. 使用 `schedule_once` 调度下一次心跳（间隔为 `this.ping_timeout` 秒）。
+
+> ⚠️ 此方法采用递归调度方式实现定时循环。
+
+---
+
+### `charsize_sizing()`
+
+根据全局字体设置调整终端字号。
+
+#### 依赖
+
+```js
+var cs = bricks.app.charsize; // 假设为数字（例如 14）
+```
+
+#### 实现
+
+```js
+this.term.setOption('fontSize', cs);
+```
+
+---
+
+### `term_resize()`
+
+响应外部容器尺寸变化的回调函数。
+
+#### 功能
+
+调用 `fitAddon.fit()` 让终端自适应新尺寸。
+
+> 注释掉 `this.send_term_size()` 可能是为了防止重复发送（已在 xterm 的 `onResize` 中处理）。
+
+---
+
+## 资源释放与销毁
+
+### `close_websocket()`
+
+关闭并清理 WebSocket 连接。
+
+#### 清理项
+
+- 调用 `close(1000, 'close now')`
+- 解除所有事件监听器
+- 将 `this.socket` 设为 `null`
+
+#### 异常处理
+
+捕获任何错误并重置 `socket` 引用，确保不会残留无效引用。
+
+---
+
+### `close_terminal()`
+
+关闭并销毁 xterm 终端实例。
+
+#### 清理项
+
+- 调用 `fitAddon.dispose()`
+- 调用 `term.dispose()`
+- 将 `this.term` 设为 `null`
+
+---
+
+### `destroy()`
+
+完整销毁组件资源（响应 `'domoff'` 事件）。
+
+#### 执行步骤
+
+1. 打印调试日志
+2. 取消心跳任务（如果存在）
+3. 解绑 `element_resize` 事件
+4. 关闭 WebSocket（如有）
+5. 销毁终端实例（如有）
+
+#### 日志输出示例
+
+```text
+------domoff event, destory this widget
+---1--domoff event, destory this widget
+---2--domoff event, destory this widget
+---3--domoff event, destory this widget
+```
+
+---
+
+## 事件绑定
+
+| 事件名 | 触发时机 | 处理函数 |
+|--------|---------|---------|
+| `'domon'` | DOM 元素变为可见 | `send_term_size()` |
+| `'domoff'` | DOM 元素隐藏或移除 | `destroy()` |
+| `'element_resize'` | 容器尺寸变化 | `term_resize()` |
+
+> 使用 `this.bind(event, handler)` 和 `this.unbind(...)` 管理事件。
+
+---
+
+## 静态注册
+
+```js
+bricks.Factory.register('Wterm', bricks.Wterm);
+```
+
+允许通过工厂模式创建实例：
+
+```js
+bricks.Factory.create('Wterm', options);
+```
+
+---
+
+## 使用示例
+
+```html
+<div id="terminal-container" style="width:100%; height:500px;"></div>
+
+<script>
+// 假设已加载 xterm.js 和 FitAddon
+const terminalWidget = new bricks.Wterm({
+  ws_url: 'ws://your-terminal-server/ws/session-id',
+  ping_timeout: 20
+});
+
+// 挂载到 DOM
+terminalWidget.render('#terminal-container');
+</script>
+```
+
+---
+
+## 注意事项
+
+1. **必须引入 xterm.js 和 FitAddon**
+   ```html
+   <script src="https://unpkg.com/xterm@5.x.x/lib/xterm.js"></script>
+   <script src="https://unpkg.com/xterm-addon-fit@0.x.x/lib/FitAddon.js"></script>
+   ```
+2. `schedule_once(fn, delay)` 需要全局可用（通常由框架提供）。
+3. 字体大小依赖 `bricks.app.charsize`，请确保其存在。
+4. WebSocket 服务需支持以下协议字段：
+   - `type: "input"` / `"resize"` / `"heartbeat"`
+   - 并能返回 `type: "data"` 或 `"heartbeat"` 消息。
+
+---
+
+## 版本兼容性
+
+| 库名 | 推荐版本 |
+|------|----------|
+| xterm.js | `>= 4.0.0 < 6.0.0` |
+| xterm-addon-fit | 对应版本 |
+
+---
+
+## 总结
+
+`bricks.Wterm` 是一个功能完整的 Web 终端组件，适用于远程 shell、在线 IDE、调试工具等场景。其设计模块化、生命周期清晰，结合 bricks 框架可轻松集成进复杂前端系统。
+
+--- 
+
+✅ **建议扩展方向**：
+- 支持主题切换
+- 添加复制粘贴快捷键拦截
+- 增加连接失败重试机制
+- 支持二进制数据传输（如图像）
\ No newline at end of file