agent-configs 1.0.0

package/skills/bk-chat-x/references/shortcuts-guide.md

@@ -0,0 +1,375 @@
+# 快捷指令配置指南
+
+## Shortcut 类型定义
+
+```typescript
+interface Shortcut {
+  id: string;                      // 唯一标识
+  name: string;                    // 显示名称
+  description?: string;            // 描述
+  icon?: string | VNode | ((h) => Component | VNode);  // 图标
+  components?: ShortcutComponent[];  // 表单组件配置
+  formModel?: Record<string, unknown>;  // 表单初始值
+}
+```
+
+## 基础快捷指令
+
+不带表单的简单快捷指令：
+
+```typescript
+const shortcuts: Shortcut[] = [
+  { id: 'ask', name: '问问小鲸' },
+  { id: 'translate', name: '翻译' },
+  { id: 'explain', name: '解释' },
+  { id: 'summarize', name: '总结' },
+];
+```
+
+## 带图标的快捷指令
+
+```typescript
+import { ThinkingIcon, CopyIcon } from '@blueking/chat-x';
+
+const shortcuts: Shortcut[] = [
+  {
+    id: 'ask',
+    name: '问问小鲸',
+    icon: ThinkingIcon,  // 组件图标
+  },
+  {
+    id: 'translate',
+    name: '翻译',
+    icon: '🌐',  // 字符串图标
+  },
+  {
+    id: 'code',
+    name: '代码生成',
+    icon: () => CopyIcon,  // 函数返回组件
+  },
+];
+```
+
+## 带表单的快捷指令
+
+### ShortcutComponent 类型
+
+```typescript
+interface ShortcutComponent {
+  type: 'input' | 'text' | 'textarea' | 'number' | 'select' | 'radioGroup' | 'checkboxGroup' | 'switcher';
+  key: string;                      // 表单字段 key
+  name?: string;                    // 字段标签
+  default?: unknown;                // 默认值
+  fillBack?: boolean;               // 是否回填选中文本
+  fillRegx?: RegExp;                // 回填内容正则验证
+  props?: Record<string, any>;      // 组件 props
+  formItemProps?: Record<string, any>;  // FormItem props
+}
+```
+
+### 表单组件类型
+
+| type | 说明 | 对应 bkui-vue 组件 |
+|------|------|-------------------|
+| `input` | 单行输入框 | Input |
+| `text` | 单行输入框 (同 input) | Input |
+| `textarea` | 多行文本框 | Input[type=textarea] |
+| `number` | 数字输入框 | Input[type=number] |
+| `select` | 下拉选择 | Select |
+| `radioGroup` | 单选组 | Radio.Group |
+| `checkboxGroup` | 多选组 | Checkbox.Group |
+| `switcher` | 开关 | Switcher |
+
+### 完整示例
+
+```typescript
+const shortcuts: Shortcut[] = [
+  {
+    id: 'translate',
+    name: '翻译',
+    description: '将选中文本翻译成目标语言',
+    components: [
+      // 下拉选择
+      {
+        type: 'select',
+        key: 'targetLang',
+        name: '目标语言',
+        default: 'en',
+        props: {
+          options: [
+            { label: '英文', value: 'en' },
+            { label: '中文', value: 'zh' },
+            { label: '日文', value: 'ja' },
+            { label: '韩文', value: 'ko' },
+          ],
+          clearable: false,
+        },
+        formItemProps: {
+          required: true,
+        },
+      },
+      // 多行文本 (回填选中文本)
+      {
+        type: 'textarea',
+        key: 'content',
+        name: '翻译内容',
+        fillBack: true,  // 自动填充选中的文本
+        props: {
+          rows: 4,
+          placeholder: '请输入要翻译的内容',
+        },
+      },
+    ],
+    formModel: {
+      targetLang: 'en',
+      content: '',
+    },
+  },
+
+  {
+    id: 'code-gen',
+    name: '代码生成',
+    components: [
+      // 单行输入
+      {
+        type: 'input',
+        key: 'language',
+        name: '编程语言',
+        default: 'JavaScript',
+        props: {
+          placeholder: '如：JavaScript、Python',
+        },
+      },
+      // 数字输入
+      {
+        type: 'number',
+        key: 'maxLines',
+        name: '最大行数',
+        default: 50,
+        props: {
+          min: 1,
+          max: 500,
+        },
+      },
+      // 单选组
+      {
+        type: 'radioGroup',
+        key: 'style',
+        name: '代码风格',
+        default: 'concise',
+        props: {
+          options: [
+            { label: '简洁', value: 'concise' },
+            { label: '详细', value: 'detailed' },
+          ],
+        },
+      },
+      // 多选组
+      {
+        type: 'checkboxGroup',
+        key: 'features',
+        name: '包含功能',
+        default: ['comments'],
+        props: {
+          options: [
+            { label: '注释', value: 'comments' },
+            { label: '错误处理', value: 'error-handling' },
+            { label: '类型定义', value: 'types' },
+          ],
+        },
+      },
+      // 开关
+      {
+        type: 'switcher',
+        key: 'async',
+        name: '异步函数',
+        default: false,
+      },
+      // 描述文本
+      {
+        type: 'textarea',
+        key: 'description',
+        name: '功能描述',
+        fillBack: true,
+        props: {
+          rows: 4,
+          placeholder: '请详细描述需要生成的代码功能',
+        },
+      },
+    ],
+  },
+
+  {
+    id: 'trace-analysis',
+    name: 'Trace 分析',
+    components: [
+      {
+        type: 'text',
+        key: 'project_name',
+        name: '项目名称',
+        default: '',
+        placeholder: '请输入项目名称',
+        required: true,
+        fillBack: true,
+        fillRegx: /^[a-zA-Z0-9]+$/,  // 回填内容验证
+      },
+      {
+        type: 'number',
+        key: 'quantity',
+        name: '数量',
+        default: '10',
+        min: 1,
+        max: 100,
+        required: true,
+      },
+      {
+        type: 'select',
+        key: 'project_type',
+        name: '项目类型',
+        required: true,
+        options: [
+          { label: '类型A', value: 'A' },
+          { label: '类型B', value: 'B' },
+        ],
+      },
+    ],
+  },
+];
+```
+
+## 使用快捷指令
+
+### 在 ChatInput 中使用
+
+```vue
+<template>
+  <ChatInput
+    v-model="input"
+    :shortcuts="shortcuts"
+    :shortcut-id="selectedShortcutId"
+    @select-shortcut="handleSelectShortcut"
+    @delete-shortcut="handleDeleteShortcut"
+  />
+</template>
+
+<script setup lang="ts">
+const selectedShortcutId = ref<string | null>(null);
+
+const handleSelectShortcut = (shortcut: Shortcut, text?: string) => {
+  selectedShortcutId.value = shortcut.id;
+  
+  // 如果有表单组件，显示 ShortcutRender
+  if (shortcut.components?.length) {
+    showShortcutForm.value = true;
+  }
+};
+
+const handleDeleteShortcut = () => {
+  selectedShortcutId.value = null;
+};
+</script>
+```
+
+### 配合 ShortcutRender 使用
+
+```vue
+<template>
+  <!-- 快捷指令表单与输入框互斥 -->
+  <ShortcutRender
+    v-if="selectedShortcut?.components?.length"
+    :name="selectedShortcut.name"
+    :components="selectedShortcut.components"
+    :form-model="selectedShortcut.formModel"
+    @close="handleCloseShortcut"
+    @submit="handleSubmitShortcut"
+  />
+  <ChatInput
+    v-else
+    v-model="input"
+    :shortcuts="shortcuts"
+    :shortcut-id="selectedShortcut?.id"
+    @select-shortcut="handleSelectShortcut"
+  />
+</template>
+
+<script setup lang="ts">
+const selectedShortcut = ref<Shortcut | null>(null);
+
+const handleSelectShortcut = (shortcut: Shortcut, text?: string) => {
+  // 如果有 fillBack 的组件，填充选中文本
+  if (shortcut.components?.length && text) {
+    const fillBackComponent = shortcut.components.find(c => c.fillBack);
+    if (fillBackComponent) {
+      shortcut.formModel = {
+        ...shortcut.formModel,
+        [fillBackComponent.key]: text,
+      };
+    }
+  }
+  selectedShortcut.value = shortcut;
+};
+
+const handleCloseShortcut = () => {
+  selectedShortcut.value = null;
+};
+
+const handleSubmitShortcut = (formModel: Record<string, unknown>) => {
+  console.log('提交快捷指令:', selectedShortcut.value?.id, formModel);
+  
+  // 构造消息发送
+  const message = buildMessageFromShortcut(selectedShortcut.value, formModel);
+  sendMessage(message);
+  
+  selectedShortcut.value = null;
+};
+</script>
+```
+
+### 在 AiSelection 中使用
+
+```vue
+<template>
+  <AiSelection
+    v-model:visible="visible"
+    :shortcuts="shortcuts"
+    :max-shortcut-count="3"
+    @select-shortcut="handleSelectShortcut"
+  />
+</template>
+
+<script setup lang="ts">
+const handleSelectShortcut = (shortcut: Shortcut, selectedText: string) => {
+  // 无表单的快捷指令直接执行
+  if (!shortcut.components?.length) {
+    executeShortcut(shortcut, selectedText);
+    return;
+  }
+  
+  // 有表单的快捷指令，预填充选中文本后显示表单
+  const fillBackComponent = shortcut.components.find(c => c.fillBack);
+  if (fillBackComponent) {
+    shortcut.formModel = {
+      ...shortcut.formModel,
+      [fillBackComponent.key]: selectedText,
+    };
+  }
+  selectedShortcut.value = shortcut;
+};
+</script>
+```
+
+## 表单布局规则
+
+ShortcutRender 使用两列网格布局：
+
+- `textarea` 类型组件自动占据整行
+- 最后一个组件如果是奇数位置，自动占据整行
+- 提交按钮区域固定在底部
+
+## 最佳实践
+
+1. **ID 唯一性**：确保每个 shortcut 的 id 唯一
+2. **fillBack 使用**：只给需要回填选中文本的组件设置 `fillBack: true`
+3. **默认值**：为表单组件设置合理的默认值
+4. **验证规则**：使用 `formItemProps.required` 设置必填项
+5. **图标一致性**：使用组件库提供的图标保持风格统一