@next-bricks/visual-builder 1.39.15 → 1.39.17

package/docs/chat-conversation.md

@@ -1,9 +1,34 @@
-用于 Visual Builder 的智能聊天对话列表
+---
+tagName: visual-builder.chat-conversation
+displayName: WrappedVisualBuilderChatConversation
+description: 用于 Visual Builder 的智能聊天对话列表，解析 AI 回复中的 Storyboard 代码块并触发更新事件
+category: ""
+source: "@next-bricks/visual-builder"
+---
+
+# visual-builder.chat-conversation
+
+> 用于 Visual Builder 的智能聊天对话列表，解析 AI 回复中的 Storyboard 代码块并触发更新事件
+
+## Props
+
+| 属性          | 类型        | 必填 | 默认值 | 说明                                                                            |
+| ------------- | ----------- | ---- | ------ | ------------------------------------------------------------------------------- |
+| messages      | `Message[]` | 否   | -      | 对话消息列表，包含用户和 AI 助手的消息，支持流式（partial）和失败（failed）状态 |
+| errorBoundary | `boolean`   | 否   | -      | 是否为解析出的砖块启用错误边界，防止单个砖块异常导致整个预览崩溃                |
+
+## Events
+
+| 事件              | detail                               | 说明                                     |
+| ----------------- | ------------------------------------ | ---------------------------------------- |
+| storyboard.update | `BrickConf[]` — 解析出的砖块配置列表 | 从 AI 回复中解析出新的 Storyboard 时触发 |
 
 ## Examples
 
 ### Basic
 
+展示包含用户消息和 AI 回复的完整对话列表，AI 回复中嵌入了 Storyboard 代码块。
+
 ````yaml preview
 brick: visual-builder.chat-conversation
 properties:
@@ -16,9 +41,9 @@ properties:
         好的，我们来逐步确认页面的各个区块需求。
 
         1. **页头区**：您需要在这个区域放置什么内容？比如标题、横幅图片或者搜索框等。
-        2. **全局操作区**：您希望有哪些全局操作的按钮？如您所示，已有“管理”、“刷新”、“新建”、“删除”、“执行”、“导入”和“导出”，这些都足够了吗？
+        2. **全局操作区**：您希望有哪些全局操作的按钮？如您所示，已有"管理"、"刷新"、"新建"、"删除"、"执行"、"导入"和"导出"，这些都足够了吗？
         3. **标签导航区**：是否需要多个标签页？如果有，需要显示哪些内容或数据？
-        4. **数据控制区**：对于搜索，需要哪些字段作为搜索条件？“最近访问”和“基础筛选”需要哪些具体筛选条件？
+        4. **数据控制区**：对于搜索，需要哪些字段作为搜索条件？"最近访问"和"基础筛选"需要哪些具体筛选条件？
         5. **列表区**：列表中应显示主机的哪些属性？例如，是否显示`主机名`、`IP`、`供应商`等信息？是否需要编辑和删除功能？列表是否可排序？用户是否可以多选列表项？分页功能需要吗？
 
         请根据您的需求回答这些问题，或者告诉我哪些区块的默认设置即可。
@@ -40,43 +65,19 @@ properties:
         ```
 
         ```easy_cmd_vb_block_page
-        [{"uuid": "96e55a2a556049eba1e5c1a8cd1e6ef3", "seq": 0, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "包含新建和删除按钮", "user_desc": "", "storyboard": null, "type": "block", "name": "全局操作区", "children": ["d7ef5946776445ba96ebf2beb2f680a5", "da3e65baf08d4fc28b938d1efd768265"], "parent": "", "properties": null, "hasContainer": false}, {"uuid": "d7ef5946776445ba96ebf2beb2f680a5", "seq": 0, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "生成一个新建按钮，textContent为新建，type为primary（主要按钮），大小为medium，形状为默认方形，非禁用状态，无危险状态，无图标，无tooltip", "user_desc": "", "storyboard": null, "type": "item", "name": "新建", "children": [], "parent": "96e55a2a556049eba1e5c1a8cd1e6ef3", "properties": null, "hasContainer": false}, {"uuid": "da3e65baf08d4fc28b938d1efd768265", "seq": 1, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "生成一个删除按钮，textContent为删除，type为danger（危险按钮），大小为medium，形状为默认方形，非禁用状态，有危险状态，无图标，无tooltip", "user_desc": "", "storyboard": null, "type": "item", "name": "删除", "children": [], "parent": "96e55a2a556049eba1e5c1a8cd1e6ef3", "properties": null, "hasContainer": false}, {"uuid": "92c07992c61d4f43b41e6a56e500622a", "seq": 1, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "提供按IP搜索的功能", "user_desc": "", "storyboard": null, "type": "block", "name": "数据控制区", "children": ["e2f986f8379f4fd4bd3627855051c50e"], "parent": "", "properties": null, "hasContainer": true}, {"uuid": "e2f986f8379f4fd4bd3627855051c50e", "seq": 0, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "eo-search", "brick_desc": "提供按IP地址搜索的功能，允许用户输入IP地址进行精确匹配或模糊搜索", "user_desc": "", "storyboard": null, "type": "item", "name": "IP搜索", "children": [], "parent": "92c07992c61d4f43b41e6a56e500622a", "properties": null, "hasContainer": false}, {"uuid": "a66ff62152ea4b808f2e5d957c24b2ef", "seq": 2, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "展示每条主机的供应商、主机名、MAC地址和操作系统", "user_desc": "", "storyboard": null, "type": "block", "name": "列表区", "children": ["8ed6175b7bc94b40b28f1f7687cb1a3a", "a52c680f3e364eff84fc169b8d8c191e", "c04fef1e64ca4200a5843b579f71fbcf", "0b485a8a1b924d54adb8914763096723"], "parent": "", "properties": null, "hasContainer": true}, {"uuid": "8ed6175b7bc94b40b28f1f7687cb1a3a", "seq": 0, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "使用文本构件，显示供应商信息。", "user_desc": "", "storyboard": null, "type": "item", "name": "供应商", "children": [], "parent": "a66ff62152ea4b808f2e5d957c24b2ef", "properties": null, "hasContainer": false}, {"uuid": "a52c680f3e364eff84fc169b8d8c191e", "seq": 1, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "使用链接构件，显示主机名，跳转到主机详情页面。", "user_desc": "", "storyboard": null, "type": "item", "name": "主机名", "children": [], "parent": "a66ff62152ea4b808f2e5d957c24b2ef", "properties": null, "hasContainer": false}, {"uuid": "c04fef1e64ca4200a5843b579f71fbcf", "seq": 2, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "使用文本构件，显示MAC地址信息。", "user_desc": "", "storyboard": null, "type": "item", "name": "物理地址", "children": [], "parent": "a66ff62152ea4b808f2e5d957c24b2ef", "properties": null, "hasContainer": false}, {"uuid": "0b485a8a1b924d54adb8914763096723", "seq": 3, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "使用文本构件，显示操作系统类型信息。", "user_desc": "", "storyboard": null, "type": "item", "name": "操作系统类型", "children": [], "parent": "a66ff62152ea4b808f2e5d957c24b2ef", "properties": null, "hasContainer": false}]
-        ```
-
-        ```easy_cmd_vb_block_storyboard
-        {"uuid": "d7ef5946776445ba96ebf2beb2f680a5", "storyboard": {"brick": "eo-button", "events": {"click": []}, "properties": {"textContent": "新建", "type": "primary", "size": "medium", "shape": "default", "buttonStyle": {"padding": "0 8px"}, "dataset": {"testid": "create-eo-button"}}}}
-        ```
-
-        ```easy_cmd_vb_block_storyboard
-        {"uuid": "da3e65baf08d4fc28b938d1efd768265", "storyboard": {"brick": "eo-button", "events": {"click": []}, "properties": {"textContent": "删除", "type": "danger", "size": "medium", "buttonStyle": {"padding": "0px 8px"}, "danger": true, "dataset": {"testid": "delete-button"}, "properties": {"danger": true, "type": "danger"}}}}
-        ```
-
-        ```easy_cmd_vb_block_storyboard
-        {"uuid": "92c07992c61d4f43b41e6a56e500622a", "storyboard": {"brick": "eo-form", "properties": {"layout": "inline"}}}
-        ```
-
-        ```easy_cmd_vb_block_storyboard
-        {"uuid": "e2f986f8379f4fd4bd3627855051c50e", "storyboard": {"brick": "eo-search", "events": {"search": []}, "properties": {"placeholder": "按IP地址搜索", "dataset": {"testid": "search"}}}}
+        [{"uuid": "96e55a2a556049eba1e5c1a8cd1e6ef3", "seq": 0, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "包含新建和删除按钮", "user_desc": "", "storyboard": null, "type": "block", "name": "全局操作区", "children": ["d7ef5946776445ba96ebf2beb2f680a5", "da3e65baf08d4fc28b938d1efd768265"], "parent": "", "properties": null, "hasContainer": false}, {"uuid": "d7ef5946776445ba96ebf2beb2f680a5", "seq": 0, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "生成一个新建按钮，textContent为新建，type为primary（主要按钮），大小为medium，形状为默认方形，非禁用状态，无危险状态，无图标，无tooltip", "user_desc": "", "storyboard": null, "type": "item", "name": "新建", "children": [], "parent": "96e55a2a556049eba1e5c1a8cd1e6ef3", "properties": null, "hasContainer": false}, {"uuid": "da3e65baf08d4fc28b938d1efd768265", "seq": 1, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "生成一个删除按钮，textContent为删除，type为danger（危险按钮），大小为medium，形状为默认方形，非禁用状态，有危险状态，无图标，无tooltip", "user_desc": "", "storyboard": null, "type": "item", "name": "删除", "children": [], "parent": "96e55a2a556049eba1e5c1a8cd1e6ef3", "properties": null, "hasContainer": false}, {"uuid": "a66ff62152ea4b808f2e5d957c24b2ef", "seq": 2, "conversationId": "db2e41dc-932c-4f76-aad4-19da09bea036", "brick": "", "brick_desc": "展示每条主机的IP、主机名、运营状态和创建时间", "user_desc": "", "storyboard": null, "type": "block", "name": "列表区", "children": [], "parent": "", "properties": null, "hasContainer": true}]
         ```
 
         ```easy_cmd_vb_block_storyboard
-        {"uuid": "a66ff62152ea4b808f2e5d957c24b2ef", "storyboard": {"brick": "eo-next-table", "properties": {"columns": [{"title": "供应商", "dataIndex": "provider", "useChildren": "[provider]"}, {"title": "主机名", "dataIndex": "hostname", "useChildren": "[hostname]"}, {"title": "MAC地址", "dataIndex": "_mac", "useChildren": "[_mac]"}, {"title": "操作系统", "dataIndex": "osSystem", "useChildren": "[osSystem]"}], "dataSource": "<% CTX.hostList %>"}, "context": [{"name": "hostList", "value": {"list": [{"provider": "供应商A", "hostname": "主机1", "_mac": "00:11:22:33:44:55", "osSystem": "Windows 10"}, {"provider": "供应商B", "hostname": "主机2", "_mac": "AA:BB:CC:DD:EE:FF", "osSystem": "Ubuntu 20.04"}], "total": 2}}]}}
+        {"uuid": "d7ef5946776445ba96ebf2beb2f680a5", "storyboard": {"brick": "eo-button", "events": {"click": []}, "properties": {"textContent": "新建", "type": "primary", "size": "medium"}}}
         ```
 
         ```easy_cmd_vb_block_storyboard
-        {"uuid": "8ed6175b7bc94b40b28f1f7687cb1a3a", "storyboard": {"brick": "eo-text", "properties": {"textContent": "<% DATA.cellData %>", "dataset": {"testid": "textContent"}}, "slot": "[provider]"}}
+        {"uuid": "da3e65baf08d4fc28b938d1efd768265", "storyboard": {"brick": "eo-button", "events": {"click": []}, "properties": {"textContent": "删除", "type": "danger", "size": "medium", "danger": true}}}
         ```
 
         ```easy_cmd_vb_block_storyboard
-        {"uuid": "a52c680f3e364eff84fc169b8d8c191e", "storyboard": {"brick": "eo-link", "events": {"click": []}, "properties": {"url": "<% DATA.cellData %>", "target": "_blank", "showIcon": true, "textContent": "<% DATA.cellData %>", "dataset": {"testid": "nodeUrl"}}, "slot": "[hostname]"}}
-        ```
-
-        ```easy_cmd_vb_block_storyboard
-        {"uuid": "c04fef1e64ca4200a5843b579f71fbcf", "storyboard": {"brick": "eo-text", "properties": {"textContent": "<% DATA.cellData %>", "dataset": {"testid": "textContent"}}, "slot": "[_mac]"}}
-        ```
-
-        ```easy_cmd_vb_block_storyboard
-        {"uuid": "0b485a8a1b924d54adb8914763096723", "storyboard": {"brick": "eo-text", "properties": {"textContent": "<% DATA.cellData %>", "dataset": {"testid": "textContent"}}, "slot": "[osSystem]"}}
+        {"uuid": "a66ff62152ea4b808f2e5d957c24b2ef", "storyboard": {"brick": "eo-next-table", "properties": {"columns": [{"title": "IP", "dataIndex": "ip"}, {"title": "主机名", "dataIndex": "hostname"}, {"title": "运营状态", "dataIndex": "status"}, {"title": "创建时间", "dataIndex": "createTime"}], "dataSource": {"list": [{"ip": "192.168.1.1", "hostname": "host-001", "status": "运行中", "createTime": "2024-01-01"}]}}}}
         ```
       key: 4
       partial: true
@@ -87,6 +88,8 @@ events:
 
 ### Errors
 
+展示包含失败消息的对话，failed 状态的消息会以错误样式展示。
+
 ```yaml preview
 brick: visual-builder.chat-conversation
 properties:
@@ -103,3 +106,20 @@ properties:
       key: 3
       failed: true
 ```
+
+### With Error Boundary
+
+启用错误边界后，单个砖块渲染失败不会导致整个预览崩溃。
+
+```yaml preview
+brick: visual-builder.chat-conversation
+properties:
+  errorBoundary: true
+  messages:
+    - role: user
+      content: 生成一个简单页面
+      key: 1
+    - role: assistant
+      content: 好的，正在生成...
+      key: 2
+```

package/docs/chat-conversation.react.md

@@ -0,0 +1,115 @@
+---
+tagName: visual-builder.chat-conversation
+displayName: WrappedVisualBuilderChatConversation
+description: 用于 Visual Builder 的智能聊天对话列表，解析 AI 回复中的 Storyboard 代码块并触发更新事件
+category: ""
+source: "@next-bricks/visual-builder"
+---
+
+# WrappedVisualBuilderChatConversation
+
+> 用于 Visual Builder 的智能聊天对话列表，解析 AI 回复中的 Storyboard 代码块并触发更新事件
+
+## 导入
+
+```tsx
+import { WrappedVisualBuilderChatConversation } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性          | 类型        | 必填 | 默认值 | 说明                                                                            |
+| ------------- | ----------- | ---- | ------ | ------------------------------------------------------------------------------- |
+| messages      | `Message[]` | 否   | -      | 对话消息列表，包含用户和 AI 助手的消息，支持流式（partial）和失败（failed）状态 |
+| errorBoundary | `boolean`   | 否   | -      | 是否为解析出的砖块启用错误边界，防止单个砖块异常导致整个预览崩溃                |
+
+## Events
+
+| 事件               | detail                               | 说明                                     |
+| ------------------ | ------------------------------------ | ---------------------------------------- |
+| onStoryboardUpdate | `BrickConf[]` — 解析出的砖块配置列表 | 从 AI 回复中解析出新的 Storyboard 时触发 |
+
+## Examples
+
+### Basic
+
+展示包含用户消息和 AI 回复的完整对话列表，AI 回复中嵌入了 Storyboard 代码块。
+
+```tsx
+<WrappedVisualBuilderChatConversation
+  messages={[
+    {
+      role: "user",
+      content: "生成一个主机列表页面",
+      key: 1,
+    },
+    {
+      role: "assistant",
+      content: "好的，我们来逐步确认页面的各个区块需求。",
+      key: 2,
+    },
+    {
+      role: "user",
+      content: "列表区展示每条主机的IP、主机名、运营状态、创建时间。",
+      key: 3,
+    },
+    {
+      role: "assistant",
+      content: "了解了您的需求，正在生成页面...",
+      key: 4,
+      partial: true,
+    },
+  ]}
+  onStoryboardUpdate={(e) => console.log(e.detail)}
+/>
+```
+
+### Errors
+
+展示包含失败消息的对话，failed 状态的消息会以错误样式展示。
+
+```tsx
+<WrappedVisualBuilderChatConversation
+  messages={[
+    {
+      role: "user",
+      content: "Create a page to show server host list.",
+      key: 1,
+    },
+    {
+      role: "assistant",
+      content: "OK, let's do it",
+      key: 2,
+      failed: true,
+    },
+    {
+      role: "assistant",
+      content: "Internal Server Error",
+      key: 3,
+      failed: true,
+    },
+  ]}
+/>
+```
+
+### With Error Boundary
+
+启用错误边界后，单个砖块渲染失败不会导致整个预览崩溃。
+
+```tsx
+<WrappedVisualBuilderChatConversation
+  errorBoundary={true}
+  messages={[
+    {
+      role: "user",
+      content: "生成一个简单页面",
+      key: 1,
+    },
+    {
+      role: "assistant",
+      content: "好的，正在生成...",
+      key: 2,
+    },
+  ]}
+/>
+```

package/docs/chat-preview.md

@@ -0,0 +1,83 @@
+---
+tagName: visual-builder.chat-preview
+displayName: WrappedVisualBuilderChatPreview
+description: Visual Builder 的聊天预览构件，在 iframe 中渲染 Storyboard 并支持元素检查模式
+category: ""
+source: "@next-bricks/visual-builder"
+---
+
+# visual-builder.chat-preview
+
+> Visual Builder 的聊天预览构件，在 iframe 中渲染 Storyboard 并支持元素检查模式
+
+## Props
+
+| 属性       | 类型                       | 必填 | 默认值 | 说明                                                             |
+| ---------- | -------------------------- | ---- | ------ | ---------------------------------------------------------------- |
+| storyboard | `BrickConf \| BrickConf[]` | 否   | -      | 要预览的砖块配置，支持单个或列表，更新后自动触发 iframe 重新渲染 |
+| theme      | `string`                   | 否   | -      | 预览的主题，例如 "dark-v2"                                       |
+| uiVersion  | `string`                   | 否   | -      | 预览的 UI 版本，例如 "8.2"                                       |
+| app        | `MicroApp`                 | 否   | -      | 预览使用的 MicroApp 配置，影响 app 上下文                        |
+| inspecting | `boolean`                  | 否   | -      | 是否开启元素检查模式，开启后鼠标悬停和点击时会显示元素轮廓高亮   |
+
+## Events
+
+| 事件                | detail                                                                          | 说明                                           |
+| ------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------- |
+| activeTarget.change | `InspectSelector \| undefined` — 当前激活的检查目标选择器，未选中时为 undefined | 用户在检查模式下点击元素时，激活目标变化时触发 |
+
+## Methods
+
+| 方法   | 参数                                 | 返回值 | 说明                                             |
+| ------ | ------------------------------------ | ------ | ------------------------------------------------ |
+| select | `(payload: InspectSelector) => void` | `void` | 向 iframe 内的预览代理发送选中指令，高亮指定元素 |
+
+## Examples
+
+### Basic
+
+展示 Chat Preview 的基本用法，传入砖块配置后在 iframe 中渲染预览。
+
+```yaml preview
+brick: visual-builder.chat-preview
+properties:
+  storyboard:
+    - brick: eo-button
+      properties:
+        textContent: 预览按钮
+        type: primary
+```
+
+### With Theme
+
+指定预览主题和 UI 版本，使预览效果与目标环境匹配。
+
+```yaml preview
+brick: visual-builder.chat-preview
+properties:
+  theme: dark-v2
+  uiVersion: "8.2"
+  storyboard:
+    - brick: eo-button
+      properties:
+        textContent: 暗色主题预览
+        type: primary
+```
+
+### Inspect Mode
+
+开启检查模式，鼠标悬停时显示元素轮廓，点击时触发激活目标变化事件。
+
+```yaml preview
+brick: visual-builder.chat-preview
+properties:
+  inspecting: true
+  storyboard:
+    - brick: eo-button
+      properties:
+        textContent: 点击以检查
+        type: primary
+events:
+  activeTarget.change:
+    action: console.log
+```

package/docs/chat-preview.react.md

@@ -0,0 +1,105 @@
+---
+tagName: visual-builder.chat-preview
+displayName: WrappedVisualBuilderChatPreview
+description: Visual Builder 的聊天预览构件，在 iframe 中渲染 Storyboard 并支持元素检查模式
+category: ""
+source: "@next-bricks/visual-builder"
+---
+
+# WrappedVisualBuilderChatPreview
+
+> Visual Builder 的聊天预览构件，在 iframe 中渲染 Storyboard 并支持元素检查模式
+
+## 导入
+
+```tsx
+import { WrappedVisualBuilderChatPreview } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性       | 类型                       | 必填 | 默认值 | 说明                                                             |
+| ---------- | -------------------------- | ---- | ------ | ---------------------------------------------------------------- |
+| storyboard | `BrickConf \| BrickConf[]` | 否   | -      | 要预览的砖块配置，支持单个或列表，更新后自动触发 iframe 重新渲染 |
+| theme      | `string`                   | 否   | -      | 预览的主题，例如 "dark-v2"                                       |
+| uiVersion  | `string`                   | 否   | -      | 预览的 UI 版本，例如 "8.2"                                       |
+| app        | `MicroApp`                 | 否   | -      | 预览使用的 MicroApp 配置，影响 app 上下文                        |
+| inspecting | `boolean`                  | 否   | -      | 是否开启元素检查模式，开启后鼠标悬停和点击时会显示元素轮廓高亮   |
+
+## Events
+
+| 事件                 | detail                                                                          | 说明                                           |
+| -------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------- |
+| onActiveTargetChange | `InspectSelector \| undefined` — 当前激活的检查目标选择器，未选中时为 undefined | 用户在检查模式下点击元素时，激活目标变化时触发 |
+
+## Methods
+
+| 方法   | 参数                                 | 返回值 | 说明                                             |
+| ------ | ------------------------------------ | ------ | ------------------------------------------------ |
+| select | `(payload: InspectSelector) => void` | `void` | 向 iframe 内的预览代理发送选中指令，高亮指定元素 |
+
+## Examples
+
+### Basic
+
+展示 Chat Preview 的基本用法，传入砖块配置后在 iframe 中渲染预览。
+
+```tsx
+<WrappedVisualBuilderChatPreview
+  storyboard={[
+    {
+      brick: "eo-button",
+      properties: {
+        textContent: "预览按钮",
+        type: "primary",
+      },
+    },
+  ]}
+/>
+```
+
+### With Theme
+
+指定预览主题和 UI 版本，使预览效果与目标环境匹配。
+
+```tsx
+<WrappedVisualBuilderChatPreview
+  theme="dark-v2"
+  uiVersion="8.2"
+  storyboard={[
+    {
+      brick: "eo-button",
+      properties: {
+        textContent: "暗色主题预览",
+        type: "primary",
+      },
+    },
+  ]}
+/>
+```
+
+### Inspect Mode
+
+开启检查模式，鼠标悬停时显示元素轮廓，点击时触发激活目标变化事件。
+
+```tsx
+const ref = useRef<any>();
+
+<WrappedVisualBuilderChatPreview
+  ref={ref}
+  inspecting={true}
+  storyboard={[
+    {
+      brick: "eo-button",
+      properties: {
+        textContent: "点击以检查",
+        type: "primary",
+      },
+    },
+  ]}
+  onActiveTargetChange={(e) => console.log(e.detail)}
+/>
+<button onClick={() => ref.current?.select({ iid: "item:xxx" })}>
+  Select Element
+</button>
+```

package/docs/contract-select.md

@@ -0,0 +1,97 @@
+---
+tagName: visual-builder.contract-select
+displayName: WrappedVisualBuilderContractSelect
+description: 契约选择构件，提供契约名称和版本的联动选择，格式为 `contractName@namespace:version`，支持在表单中使用
+category: ""
+source: "@next-bricks/visual-builder"
+---
+
+# visual-builder.contract-select
+
+> 契约选择构件，提供契约名称和版本的联动选择，格式为 `contractName@namespace:version`，支持在表单中使用
+
+## Props
+
+| 属性     | 类型                                                       | 必填 | 默认值 | 说明                                                      |
+| -------- | ---------------------------------------------------------- | ---- | ------ | --------------------------------------------------------- |
+| name     | `string`                                                   | 否   | -      | 表单字段名                                                |
+| required | `boolean`                                                  | 否   | -      | 是否为必填项                                              |
+| label    | `string`                                                   | 否   | -      | 表单项标签                                                |
+| value    | `any`                                                      | 否   | -      | 当前选中的契约值，格式为 `contractName@namespace:version` |
+| suffix   | `{ useBrick: UseSingleBrickConf \| UseSingleBrickConf[] }` | 否   | -      | 输入框后缀内容，使用 useBrick 自定义渲染                  |
+
+## Events
+
+| 事件   | detail                                                                 | 说明                 |
+| ------ | ---------------------------------------------------------------------- | -------------------- |
+| change | `string` — 选中的契约值字符串，格式为 `contractName@namespace:version` | 契约选择值变化时触发 |
+
+## Examples
+
+### Basic
+
+展示契约选择构件的基本用法，搜索并选择契约名称和版本。
+
+```yaml preview
+brick: visual-builder.contract-select
+properties:
+  label: 契约
+  name: contract
+events:
+  change:
+    action: console.log
+```
+
+### Required Field
+
+在表单中设置必填校验。
+
+```yaml preview
+brick: eo-form
+events:
+  validate.success:
+    action: console.log
+children:
+  - brick: visual-builder.contract-select
+    properties:
+      label: 契约
+      name: contract
+      required: true
+  - brick: eo-submit-buttons
+    properties:
+      submitText: 提交
+```
+
+### With Value
+
+设置初始契约值。
+
+```yaml preview
+brick: visual-builder.contract-select
+properties:
+  label: 契约
+  name: contract
+  value: "easyops.api.cmdb.instance@instance.GetDetail:1.0.0"
+events:
+  change:
+    action: console.log
+```
+
+### With Suffix
+
+在选择器后添加自定义后缀内容。
+
+```yaml preview
+brick: visual-builder.contract-select
+properties:
+  label: 契约
+  name: contract
+  suffix:
+    useBrick:
+      brick: eo-button
+      properties:
+        icon:
+          lib: antd
+          icon: question-circle
+        type: text
+```

package/docs/contract-select.react.md

@@ -0,0 +1,95 @@
+---
+tagName: visual-builder.contract-select
+displayName: WrappedVisualBuilderContractSelect
+description: 契约选择构件，提供契约名称和版本的联动选择，格式为 `contractName@namespace:version`，支持在表单中使用
+category: ""
+source: "@next-bricks/visual-builder"
+---
+
+# WrappedVisualBuilderContractSelect
+
+> 契约选择构件，提供契约名称和版本的联动选择，格式为 `contractName@namespace:version`，支持在表单中使用
+
+## 导入
+
+```tsx
+import { WrappedVisualBuilderContractSelect } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性     | 类型                                                       | 必填 | 默认值 | 说明                                                      |
+| -------- | ---------------------------------------------------------- | ---- | ------ | --------------------------------------------------------- |
+| name     | `string`                                                   | 否   | -      | 表单字段名                                                |
+| required | `boolean`                                                  | 否   | -      | 是否为必填项                                              |
+| label    | `string`                                                   | 否   | -      | 表单项标签                                                |
+| value    | `any`                                                      | 否   | -      | 当前选中的契约值，格式为 `contractName@namespace:version` |
+| suffix   | `{ useBrick: UseSingleBrickConf \| UseSingleBrickConf[] }` | 否   | -      | 输入框后缀内容，使用 useBrick 自定义渲染                  |
+
+## Events
+
+| 事件     | detail                                                                 | 说明                 |
+| -------- | ---------------------------------------------------------------------- | -------------------- |
+| onChange | `string` — 选中的契约值字符串，格式为 `contractName@namespace:version` | 契约选择值变化时触发 |
+
+## Examples
+
+### Basic
+
+展示契约选择构件的基本用法，搜索并选择契约名称和版本。
+
+```tsx
+<WrappedVisualBuilderContractSelect
+  label="契约"
+  name="contract"
+  onChange={(e) => console.log(e.detail)}
+/>
+```
+
+### Required Field
+
+在表单中设置必填校验。
+
+```tsx
+<WrappedEoForm onValidateSuccess={(e) => console.log(e.detail)}>
+  <WrappedVisualBuilderContractSelect
+    label="契约"
+    name="contract"
+    required={true}
+  />
+  <WrappedEoSubmitButtons submitText="提交" />
+</WrappedEoForm>
+```
+
+### With Value
+
+设置初始契约值。
+
+```tsx
+<WrappedVisualBuilderContractSelect
+  label="契约"
+  name="contract"
+  value="easyops.api.cmdb.instance@instance.GetDetail:1.0.0"
+  onChange={(e) => console.log(e.detail)}
+/>
+```
+
+### With Suffix
+
+在选择器后添加自定义后缀内容。
+
+```tsx
+<WrappedVisualBuilderContractSelect
+  label="契约"
+  name="contract"
+  suffix={{
+    useBrick: {
+      brick: "eo-button",
+      properties: {
+        icon: { lib: "antd", icon: "question-circle" },
+        type: "text",
+      },
+    },
+  }}
+/>
+```