@blueking/ai-blueking 2.0.0-dev.16 → 2.0.0-dev.18

package/README.md

@@ -8,11 +8,98 @@ AI-Blueking V2 是小鲸组件的重构版本，采用全新的三层架构设
 
 ### 核心特性
 
-- ✅ **模块化设计** - 清晰的职责划分，易于维护和扩展
-- ✅ **两种使用方式** - 完整组件和可嵌入的 ChatBot
-- ✅ **业务管理器** - 统一的业务逻辑封装
-- ✅ **类型安全** - 完整的 TypeScript 类型定义
-- ✅ **事件驱动** - 灵活的事件系统
+- **模块化设计** - 清晰的职责划分，易于维护和扩展
+- **两种使用方式** - 完整组件（AIBlueking）和可嵌入的 ChatBot
+- **业务管理器** - 统一的业务逻辑封装
+- **类型安全** - 完整的 TypeScript 类型定义
+- **事件驱动** - 灵活的事件系统
+
+## 本地开发
+
+### 前置条件
+
+- Node.js 18+
+- pnpm 8+
+
+### 1. 安装依赖
+
+在 monorepo 根目录（`bkui-chat-x/`）执行：
+
+```bash
+pnpm install
+```
+
+### 2. 配置环境变量
+
+在 `packages/ai-blueking/` 目录下创建 `.env.local` 文件（该文件已被 `.gitignore` 忽略，不会提交）：
+
+```bash
+# packages/ai-blueking/.env.local
+VITE_API_URL=https://your-api-endpoint.com/api/
+```
+
+> `VITE_API_URL` 是 AI Agent 后端服务的 API 地址，Playground 页面会读取此变量。
+
+### 3. 启动开发服务器
+
+在 monorepo 根目录执行：
+
+```bash
+pnpm dev:ai
+```
+
+该命令会按顺序执行：
+
+1. **构建 `@blueking/chat-helper`** — ai-blueking 依赖 chat-helper 的构建产物
+2. **启动 Vite Dev Server** — 运行 Playground 页面
+
+启动后访问 `http://localhost:8001/`，Playground 包含两个 Tab：
+
+| Tab | 说明 |
+|-----|------|
+| **AIBlueking（集成模式）** | 完整组件，含悬浮球、拖拽、划词弹窗等 |
+| **ChatBot（独立模式）** | 仅聊天功能，可嵌入任意页面 |
+
+### 4. 其他常用命令
+
+所有命令均在 monorepo 根目录执行：
+
+```bash
+# 构建 ai-blueking
+pnpm build:ai
+
+# 代码检查（ESLint + Stylelint）
+pnpm lint:ai
+
+# 构建 chat-helper（ai-blueking 的依赖）
+pnpm build:helper
+
+# 开发 chat-x UI 组件库
+pnpm dev:ui
+
+# 构建 chat-x
+pnpm build:ui
+
+# chat-x 单元测试
+pnpm test:ui
+```
+
+### Playground 文件结构
+
+```
+playground/
+├── index.html    # 入口 HTML
+├── main.js       # Vue 应用挂载
+└── App.vue       # Playground 页面（Tab 切换 AIBlueking / ChatBot）
+```
+
+Playground 的 Vite 配置位于 `scripts/vite.dev.ts`，其中 `envDir: '..'` 指向包根目录以加载 `.env.local`。
+
+### 开发注意事项
+
+- **修改 chat-helper 后**需重新执行 `pnpm build:helper`，因为 ai-blueking 引用的是 chat-helper 的构建产物
+- **修改 chat-x 后**会由 Vite 自动热更新（workspace 链接，无需手动构建）
+- **修改 ai-blueking 自身代码**会自动热更新
 
 ## 架构设计
 
@@ -39,7 +126,7 @@ AI-Blueking V2 是小鲸组件的重构版本，采用全新的三层架构设
 └─────────────────┘   └─────────────────┘
 ```
 
-## 依赖关系
+### 依赖关系
 
 - `@blueking/chat-helper` - AG-UI SDK，提供数据管理和 Agent 交互能力
 - `@blueking/chat-x` - 原子化 UI 组件库
@@ -47,26 +134,6 @@ AI-Blueking V2 是小鲸组件的重构版本，采用全新的三层架构设
 - `vue` - Vue 3.5+
 - `tippy.js` / `vue-tippy` - Tooltip 功能
 
-## 安装
-
-```bash
-# 在 monorepo 根目录
-pnpm install
-```
-
-## 开发
-
-```bash
-# 开发模式（启动 playground）
-pnpm dev:ai
-
-# 构建
-pnpm build:ai
-
-# 代码检查
-pnpm lint:ai
-```
-
 ## 使用方式
 
 ### 方式一：完整组件（AIBlueking）
@@ -105,14 +172,19 @@ const handleClose = () => {
 
 ### 方式二：核心组件（ChatBot）
 
-仅聊天功能，可嵌入到任意页面。
+仅聊天功能，可嵌入到任意页面。支持两种模式：
+
+- **独立模式**：传入 `url`，组件内部创建 chatHelper
+- **集成模式**：传入 `chatHelper` 实例，复用父组件的状态
 
 ```vue
 <template>
   <ChatBot
     :url="apiUrl"
-    :shortcuts="shortcuts"
+    height="600px"
+    max-width="800px"
     @send-message="handleSendMessage"
+    @error="handleError"
   />
 </template>
 
@@ -121,13 +193,14 @@ import { ref } from 'vue';
 import { ChatBot } from '@blueking/ai-blueking';
 
 const apiUrl = ref('https://your-api-endpoint.com');
-const shortcuts = ref([
-  { label: '快捷操作1', value: '帮我分析这段代码' },
-]);
 
 const handleSendMessage = (message: string) => {
   console.log('Message sent:', message);
 };
+
+const handleError = (error: Error) => {
+  console.error('Error:', error);
+};
 </script>
 ```
 
@@ -149,10 +222,19 @@ const handleSendMessage = (message: string) => {
 
 | 属性 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `url` | `string` | - | API 端点 URL |
+| `url` | `string` | - | API 端点 URL（独立模式） |
+| `chatHelper` | `IChatHelper` | - | ChatHelper 实例（集成模式） |
+| `height` | `string \| number` | - | 组件高度 |
+| `maxWidth` | `string \| number` | - | 最大宽度 |
 | `shortcuts` | `Shortcut[]` | `[]` | 快捷操作列表 |
-| `placeholder` | `string` | `'请输入消息...'` | 输入框占位符 |
+| `shortcutLimit` | `number` | `10` | 快捷方式数量限制 |
+| `placeholder` | `string` | - | 输入框占位符 |
 | `autoLoad` | `boolean` | `true` | 是否自动加载会话 |
+| `sessionCode` | `string` | - | 指定会话编码 |
+| `enableSelection` | `boolean` | `false` | 是否启用消息选择 |
+| `helloText` | `string` | - | 欢迎语 |
+| `prompts` | `string[]` | - | 预设提示词列表 |
+| `resources` | `IAiSlashMenuItem[]` | - | 资源列表（@ 触发） |
 
 ## Events
 
@@ -163,42 +245,57 @@ const handleSendMessage = (message: string) => {
 | `send-message` | `message: string` | 发送消息时触发 |
 | `receive-start` | - | 开始接收消息时触发 |
 | `receive-end` | - | 接收消息结束时触发 |
-| `session-initialized` | `session` | 会话初始化完成时触发 |
+| `error` | `error: Error` | 发生错误时触发 |
+| `agent-info-loaded` | `chatHelper: IChatHelper` | Agent 信息加载完成 |
+| `session-switched` | `session: ISession` | 会话切换完成 |
+| `shortcut-click` | `{ shortcut, source }` | 快捷指令被点击 |
+| `feedback` | `tool, message, reasonList, otherReason` | 用户反馈 |
 
 ## 目录结构
 
 ```
-src/
-├── ai-blueking.vue           # 主组件入口
-├── index.ts                  # 模块导出
-├── vue2.ts                   # Vue2 入口（兼容层）
-├── vue3.ts                   # Vue3 入口
-├── types.ts                  # 全局类型定义
-├── components/               # UI 组件
-│   ├── chat-bot.vue         # ChatBot 核心组件
-│   ├── ai-header/           # 头部组件
-│   ├── selection-footer/    # 选择模式底部操作栏
-│   └── types.ts
-├── composables/              # 可复用逻辑
-│   ├── use-chat-bootstrap.ts
-│   ├── use-event-bridge.ts
-│   └── ...
-├── config/                   # 配置文件
-│   ├── prop-defaults.ts
-│   └── protocol-config.ts
-├── containers/               # 容器组件
-│   └── draggable-container.vue
-├── manager/                  # 管理器层
-│   ├── component-manager.ts
-│   ├── event-types.ts
-│   └── business/            # 业务管理器
-│       ├── chat-business-manager.ts
-│       ├── session-business-manager.ts
-│       └── shortcut-manager.ts  # 快捷指令统一管理
-├── styles/                   # 样式文件
-├── utils/                    # 工具函数
-└── views/                    # 视图组件
-    └── nimbus.vue           # 悬浮球
+packages/ai-blueking/
+├── playground/               # 本地开发 Playground
+│   ├── index.html
+│   ├── main.js
+│   └── App.vue
+├── scripts/                  # 构建/开发脚本
+│   ├── vite.dev.ts          #   开发服务器配置
+│   ├── vite.build.ts        #   生产构建配置
+│   └── vite.utils.ts        #   共享配置
+├── src/
+│   ├── ai-blueking.vue      # 主组件入口（应用层）
+│   ├── index.ts             # 模块导出
+│   ├── vue2.ts              # Vue2 入口（兼容层）
+│   ├── vue3.ts              # Vue3 入口
+│   ├── types.ts             # 全局类型定义
+│   ├── components/          # UI 组件层
+│   │   ├── chat-bot.vue    #   ChatBot 核心聊天组件
+│   │   ├── ai-header/      #   头部组件（含历史会话下拉）
+│   │   ├── selection-footer/#   选择模式底部操作栏
+│   │   └── types.ts
+│   ├── composables/         # 可复用组合式逻辑
+│   │   ├── use-chat-bootstrap.ts
+│   │   ├── use-event-bridge.ts
+│   │   ├── use-history-panel.ts
+│   │   └── ...
+│   ├── config/              # 配置文件
+│   │   ├── prop-defaults.ts
+│   │   └── protocol-config.ts
+│   ├── containers/          # 容器组件（拖拽等）
+│   ├── manager/             # 管理器层
+│   │   ├── component-manager.ts
+│   │   ├── event-types.ts
+│   │   └── business/       # 业务管理器
+│   │       ├── chat-business-manager.ts
+│   │       ├── session-business-manager.ts
+│   │       └── shortcut-manager.ts
+│   ├── styles/              # 样式文件
+│   ├── utils/               # 工具函数
+│   └── views/               # 视图组件
+│       └── nimbus.vue      #   悬浮球
+├── .env.local               # 本地环境变量（git 忽略）
+└── package.json
 ```
 
 ## 划词选择功能
@@ -207,7 +304,6 @@ src/
 
 ```vue
 <template>
-  <!-- 启用划词选择 -->
   <AIBlueking
     :url="apiUrl"
     :shortcuts="shortcuts"
@@ -230,15 +326,6 @@ src/
 - 显示对应的快捷指令表单
 - 将选中文本填充到 `fillBack` 字段
 
-## 开发规范
-
-开发时请遵循 [AI-Blueking V2 开发规范](https://github.com/TencentBlueKing/bk-aidev-agent/blob/main/.cursor/rules/ai-blueking-v2-development.mdc)：
-
-1. **遵循分层架构** - 严格遵守应用层 → 组件层 → 管理器层 → SDK层 的调用顺序
-2. **事件驱动通信** - 跨组件通信必须使用事件系统
-3. **类型安全** - 所有导出 API 必须有完整的类型定义
-4. **避免重复** - 复用 chat-x 和 chat-helper 的功能
-
 ## 构建产物
 
 构建后的文件位于 `dist/` 目录：
@@ -259,12 +346,8 @@ dist/
 ## 版本兼容
 
 - **Vue 3.5+**: 完全支持（推荐）
-- **Vue 2.x**: 需要额外的兼容层（当前未实现）
+- **Vue 2.x**: 需要额外的兼容层
 
 ## License
 
 MIT
-
-## 作者
-
-Tencent BlueKing Team

package/dist/components/chat-bot.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat-bot.vue.d.ts","sourceRoot":"","sources":["../../src/components/chat-bot.vue"],"names":[],"mappings":"AAmpCE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAgB,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEzE,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAoC,MAAM,kBAAkB,CAAC;AAksC9F,QAAA,IAAI,QAAQ,IAAiC,CAAE;AAC/C,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,CAAC;AAO9C,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6EAKd,CAAC;AACH,QAAA,MAAM,YAAY,EAAS,eAAe,CAAC,OAAO,UAAU,EAAE,WAAW,CAAC,CAAC;wBACtD,OAAO,YAAY;AAAxC,wBAAyC;AAWzC,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}
+{"version":3,"file":"chat-bot.vue.d.ts","sourceRoot":"","sources":["../../src/components/chat-bot.vue"],"names":[],"mappings":"AA6pCE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAgB,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEzE,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAoC,MAAM,kBAAkB,CAAC;AA4sC9F,QAAA,IAAI,QAAQ,IAAiC,CAAE;AAC/C,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,CAAC;AAO9C,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6EAKd,CAAC;AACH,QAAA,MAAM,YAAY,EAAS,eAAe,CAAC,OAAO,UAAU,EAAE,WAAW,CAAC,CAAC;wBACtD,OAAO,YAAY;AAAxC,wBAAyC;AAWzC,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}

package/dist/vue2/index.es.min.js

@@ -27844,7 +27844,10 @@ var UIStateManager = class {
 			Ug.value = [[]], Wg.value = "", a("send-message", typeof e == "string" ? e : ""), await Bg.sendMessage(e, r, n);
 		}, l_ = async (e) => {
 			let n = I?.session.current?.value?.sessionCode;
-			return n && await I.session.uploadFile(n, e) || {};
+			if (!n) throw Error("[ChatBot] Cannot upload: no active session");
+			let r = await I.session.uploadFile(n, e);
+			if (!r?.download_url) throw Error("[ChatBot] Upload failed: no download URL returned");
+			return r;
 		}, u_ = async (e, n) => {
 			try {
 				await c_(e, Wg.value ? { property: { extra: { cite: Wg.value } } } : {});