@blueking/bkui-knowledge 0.0.1-beta.14 → 0.0.1-beta.15

package/knowledge/commands/bk-monitor-git-commit.md

@@ -0,0 +1,403 @@
+# Git 智能提交助手
+
+根据当前暂存的代码改动，自动生成 commit message 并协助完成提交流程。
+
+## 执行步骤
+
+### 1. 获取 TAPD 信息（可选）
+
+在生成 commit message 之前，尝试从分支名中获取 TAPD 信息。
+
+#### 1.1 获取当前分支名称
+
+```bash
+git branch --show-current
+```
+
+#### 1.2 提取 TAPD ID
+
+从分支名中匹配 TAPD ID，格式为 `xx/xx/#tapd_id`
+
+**匹配规则**：使用正则 `#(\d+)` 提取 ID
+
+**示例**：
+
+- `feat/ai/#1010158081130505269` → TAPD ID: `1010158081130505269`
+- `fix/bug/#1010158081130505270` → TAPD ID: `1010158081130505270`
+- `feat/new-feature` → 无 TAPD ID
+
+#### 1.3 获取 TAPD 详情
+
+**如果提取到 TAPD ID**：
+
+通过 MCP 工具获取 TAPD 单据详情：
+
+**Step 1: 从 ID 中解析 workspace_id**
+
+TAPD ID 是 19 位数字，格式为：`10` + `workspace_id(8位)` + `序列号(9位)`
+
+示例：
+| 完整 ID | 拆解 | workspace_id |
+|---------|------|--------------|
+| `1010158081130505269` | `10` + `10158081` + `130505269` | `10158081` |
+
+解析代码：`workspace_id = id.substring(2, 10)`
+
+**Step 2: 调用 MCP 工具获取详情**
+
+由于无法从 ID 本身判断单据类型（Story/Bug/Task），建议**并行调用**三个接口：
+
+```json
+// 调用 MCP: user-tapd_mcp_http
+// 工具: proxy_execute_tool
+
+// 并行调用 1: 查询需求
+{
+  "tool_name": "stories_get",
+  "tool_args": {
+    "workspace_id": "<解析出的workspace_id>",
+    "id": "<完整的19位ID>",
+    "with_v_status": "1"
+  }
+}
+
+// 并行调用 2: 查询缺陷
+{
+  "tool_name": "bugs_get",
+  "tool_args": {
+    "workspace_id": "<解析出的workspace_id>",
+    "id": "<完整的19位ID>"
+  }
+}
+
+// 并行调用 3: 查询任务
+{
+  "tool_name": "tasks_get",
+  "tool_args": {
+    "workspace_id": "<解析出的workspace_id>",
+    "id": "<完整的19位ID>"
+  }
+}
+```
+
+**Step 3: 从返回结果中提取 `title` 字段**
+
+哪个接口返回有效数据，就从该结果中提取 `title`（或 `name`）字段。
+
+**如果没有 TAPD ID**：
+
+跳过此步骤，直接进入下一步。
+
+#### 1.4 记录 TAPD 信息
+
+将获取到的信息保存，用于后续生成 commit message：
+
+- `tapd_id`: TAPD 单号
+- `tapd_title`: TAPD 标题
+
+### 2. 检查暂存文件
+
+首先检查是否有已暂存（staged）的文件：
+
+```bash
+git diff --cached --name-only
+```
+
+**判断逻辑：**
+
+- 如果没有任何暂存文件 → 直接告知用户"没有暂存的文件，请先使用 `git add` 添加要提交的文件"，然后**停止执行**
+- 如果有暂存文件 → 继续下一步
+
+### 3. 分析改动并生成 Commit Message
+
+#### 3.1 获取改动详情
+
+```bash
+# 查看暂存的文件列表
+git diff --cached --name-only
+
+# 查看暂存的代码差异
+git diff --cached
+
+# 查看最近的 commit 风格（作为参考）
+git log --oneline -5
+```
+
+#### 3.2 生成 Commit Message
+
+根据以下规则生成 commit message：
+
+**Commit 类型判断：**
+
+| 改动类型               | Commit 类型 | 示例                      |
+| ---------------------- | ----------- | ------------------------- |
+| 新增功能/组件          | feat        | `feat: 新增 xxx 组件`     |
+| 修复 bug               | fix         | `fix: 修复 xxx 问题`      |
+| 代码重构（不改变功能） | refactor    | `refactor: 重构 xxx 逻辑` |
+| 样式调整               | style       | `style: 调整 xxx 样式`    |
+| 文档更新               | docs        | `docs: 更新 xxx 文档`     |
+| 测试相关               | test        | `test: 添加 xxx 测试用例` |
+| 构建/工具配置          | chore       | `chore: 更新依赖`         |
+| 性能优化               | perf        | `perf: 优化 xxx 性能`     |
+
+**Message 格式：**
+
+根据是否有 TAPD 信息，使用不同的格式：
+
+**有 TAPD 信息时：**
+
+> ⚠️ **重要**：第一行必须是 `<type>: <tapd_title>` 的形式，TAPD 标题原样使用，不做修改。
+
+```
+<type>: <tapd_title>
+
+<AI归纳总结的改动描述>
+```
+
+格式说明：
+- **第一行**：`<type>: <tapd_title>` - 类型 + TAPD 原标题，不超过 50 字符（符合 verify-commit.js 校验）
+- **空行**：分隔标题和正文
+- **正文**：AI 根据代码 diff 归纳总结的具体改动内容
+
+示例：
+
+```
+feat: 【监控平台】新增告警通知配置功能
+
+本次改动：
+- 添加通知渠道选择组件 NotifyChannel.vue
+- 实现通知规则配置逻辑
+- 新增相关 API 接口调用
+```
+
+**无 TAPD 信息时：**
+
+```
+<type>: <subject>
+
+<AI归纳总结的改动描述>
+```
+
+示例：
+
+```
+fix: 修复列表分页异常问题
+
+本次改动：
+- 修复 pagination 组件 total 计算错误
+- 优化分页切换时的数据请求逻辑
+```
+
+#### 3.3 展示并等待确认
+
+向用户展示：
+
+1. TAPD 信息（如有）
+2. 暂存的文件列表
+3. 生成的 commit message
+4. 询问用户是否需要修改
+
+**示例输出（有 TAPD 信息）：**
+
+```
+🎫 TAPD 信息：
+- ID: 1010158081130505269
+- 标题: 【监控平台】新增告警通知配置功能
+
+📝 暂存的文件：
+- packages/chat-x/src/components/xxx/xxx.vue
+- packages/chat-x/src/components/xxx/xxx.spec.ts
+
+📄 生成的 Commit Message：
+---
+feat: 【监控平台】新增告警通知配置功能
+
+本次改动：
+- 添加组件基础结构
+- 添加单元测试
+---
+
+请确认是否使用此 commit message？
+- 如需修改，请直接告诉我新的内容
+- 确认无误请回复"确认"或"ok"
+```
+
+**示例输出（无 TAPD 信息）：**
+
+```
+📝 暂存的文件：
+- packages/chat-x/src/components/xxx/xxx.vue
+- packages/chat-x/src/components/xxx/xxx.spec.ts
+
+📄 生成的 Commit Message：
+---
+feat: 新增 xxx 组件
+
+本次改动：
+- 添加组件基础结构
+- 添加单元测试
+---
+
+请确认是否使用此 commit message？
+- 如需修改，请直接告诉我新的内容
+- 确认无误请回复"确认"或"ok"
+```
+
+**等待用户回复后再继续下一步。**
+
+### 4. 执行 Git Commit
+
+用户确认后，根据 GPG 签名配置决定执行方式。
+
+#### 4.0 检测 GPG 签名配置
+
+```bash
+git config --get commit.gpgsign
+```
+
+根据返回结果，选择不同的执行方式：
+
+---
+
+#### 4.1 情况 A：启用了 GPG 签名（返回 `true`）
+
+**不自动执行 commit**，改为输出命令让用户在终端中手动执行。
+
+> ⚠️ 由于 GPG 签名需要交互式输入密码，AI 无法代为执行，请复制以下命令到终端执行。
+
+**输出格式：**
+
+```
+🔐 检测到已启用 GPG 签名验证
+
+由于 GPG 签名需要交互式输入密码，请复制以下命令到终端执行：
+
+---
+git commit -m "$(cat <<'EOF'
+<commit message>
+EOF
+)"
+---
+
+执行后会弹出 GPG 密码输入框，输入密码即可完成提交。
+
+提交成功后，可使用以下命令推送到远程：
+git push origin <branch>
+```
+
+**流程结束，等待用户自行完成提交。**
+
+---
+
+#### 4.2 情况 B：未启用 GPG 签名（返回空或 `false`）
+
+**自动执行 commit 命令：**
+
+```bash
+git commit -m "$(cat <<'EOF'
+<commit message>
+EOF
+)"
+```
+
+#### 4.3 检查提交结果（仅适用于自动执行）
+
+**情况 B-1：提交成功**
+
+```
+✅ 提交成功！
+
+Commit: <commit hash>
+Message: <commit message>
+
+后续操作建议：
+- git push origin <branch> 推送到远程
+```
+
+**情况 B-2：Pre-commit Hook 失败**
+
+如果 pre-commit 或其他 git hook 报错：
+
+1. **捕获错误信息**
+2. **分析错误原因**
+3. **输出修复方案**
+4. **等待用户确认**
+
+**示例输出：**
+
+```
+❌ Commit 失败 - Pre-commit Hook 报错
+
+🔍 错误分析：
+- 错误类型：ESLint 检查失败
+- 问题文件：packages/chat-x/src/components/xxx/xxx.vue
+- 具体问题：
+  1. Line 25: 'unusedVar' is defined but never used
+  2. Line 42: Missing semicolon
+
+🔧 修复方案：
+1. 删除未使用的变量 'unusedVar'
+2. 在第 42 行末尾添加分号
+
+是否需要我自动修复这些问题？请回复"修复"或告诉我其他处理方式。
+```
+
+### 5. 修复并重试
+
+用户确认修复方案后：
+
+1. **执行修复操作**（编辑文件修复问题）
+2. **重新暂存修改的文件**：`git add <修复的文件>`
+3. **再次尝试提交**
+4. **如果仍有错误，重复步骤 4-5**
+
+循环直到：
+
+- ✅ 提交成功
+- 或用户选择放弃
+
+## 常见错误处理
+
+### ESLint / Biome 错误
+
+```
+修复策略：
+1. 未使用的变量 → 删除或添加使用
+2. 格式问题 → 运行 pnpm lint:ui --fix 或手动修复
+3. 导入顺序 → 调整 import 顺序
+```
+
+### TypeScript 错误
+
+```
+修复策略：
+1. 类型不匹配 → 修正类型定义
+2. 缺少类型 → 添加类型注解
+3. 属性不存在 → 检查接口定义
+```
+
+### 测试失败
+
+```
+修复策略：
+1. 断言失败 → 更新期望值或修复代码
+2. Mock 问题 → 更新 mock 配置
+3. 运行错误 → 检查测试代码逻辑
+```
+
+## 快捷使用
+
+直接执行此命令，AI 会自动：
+
+1. 从分支名获取 TAPD ID 并查询 TAPD 标题（如有）
+2. 检查暂存文件
+3. 分析改动
+4. 生成 commit message（自动融入 TAPD 标题）
+5. 引导完成提交
+
+## 注意事项
+
+1. **不会自动推送**：提交成功后不会自动 push，需要用户手动决定
+2. **保留用户控制权**：每个关键步骤都会等待用户确认
+3. **只处理暂存文件**：未 `git add` 的文件不会被提交
+4. **敏感文件检查**：如果发现 `.env`、`credentials` 等敏感文件，会发出警告

package/knowledge/commands/chat-x-generate-component.md

@@ -0,0 +1,250 @@
+# 创建 Chat-X 自定义 Message 组件
+
+根据用户需求，生成一个符合 `@blueking/chat-x` 组件库规范的自定义 message 组件。
+
+## 执行步骤
+
+### 1. 收集需求信息
+
+询问用户以下信息（如果用户没有提供）：
+
+- **组件名称**：如 `chart-message`、`table-message`、`form-message`
+- **消息角色**：如 `chart`、`table`、`form`（将用于 `role` 字段）
+- **消息内容类型**：需要渲染什么数据（图表、表格、卡片等）
+- **是否需要 Teleport**：是否需要将内容渲染到外部区域（如详情面板）
+- **交互需求**：需要哪些用户交互（点击、hover 等）
+
+### 2. 参考规范
+
+阅读以下 skill 文件获取开发规范：
+
+- `.cursor/skills/custom-component/SKILL.md` - 自定义组件开发指南
+- `.cursor/skills/chat-x-ccontribute/SKILL.md` - 项目代码规范
+
+### 3. 生成代码
+
+生成以下文件，严格遵循代码规范：
+
+#### 3.1 类型定义文件 `types/{role}-message.ts`
+
+```typescript
+import { type BaseMessage } from '@blueking/chat-x';
+
+// 自定义消息内容类型
+export interface {Role}Content {
+  // 根据用户需求定义字段
+}
+
+// 全局类型扩展
+declare global {
+  interface AIBluekingMessageMap {
+    {role}: BaseMessage<'{role}', {Role}Content>;
+  }
+}
+```
+
+#### 3.2 组件文件 `components/{role}-message/{role}-message.vue`
+
+严格遵循以下代码风格：
+
+**文件结构顺序**：`<template>` → `<script setup lang="ts">` → `<style lang="scss">`
+
+**Script 规范**：
+
+- import 顺序：Vue 核心 → 第三方库 → 本地模块 → 类型定义
+- 使用 `defineProps<Interface>()` 泛型定义 Props
+- 使用 `shallowRef` 而非 `ref` 管理状态
+- 使用 `useTemplateRef` 获取模板引用
+
+**Template 规范**：
+
+- 属性使用 kebab-case
+- 多属性时每行一个属性
+- 使用 `v-if` 条件渲染
+
+**Style 规范**：
+
+- 使用 SCSS
+- 类名使用 BEM 风格（`.{role}-message-content`）
+- 组件根类名与组件名一致
+
+#### 3.3 测试文件 `components/{role}-message/{role}-message.spec.ts`
+
+包含以下测试用例：
+
+- 组件渲染测试
+- Props 传递测试
+- 交互事件测试
+- 边界情况测试
+
+### 4. 集成指导
+
+提供如何在 `MessageContainer` 中使用该组件的代码示例。
+
+## 代码模板
+
+### Vue 组件模板
+
+```vue
+<template>
+  <div class="{role}-message">
+    <div class="{role}-message-content">
+      <!-- 主内容区域 -->
+    </div>
+    <!-- Teleport 区域（如需要） -->
+    <template v-if="panelVisible && messageSlotId">
+      <Teleport :to="messageSlotId">
+        <div class="{role}-message-panel">
+          <!-- 面板内容 -->
+        </div>
+      </Teleport>
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { onMounted, onUnmounted, shallowRef, useTemplateRef } from 'vue';
+
+  import { Button } from 'bkui-vue';
+
+  import { type BaseMessage, useMessageSlotId } from '@blueking/chat-x';
+
+  import type { {Role}Content } from '../../types/{role}-message';
+
+  // Props 定义
+  const props = defineProps<{
+    message: Partial<BaseMessage<'{role}', {Role}Content>>;
+  }>();
+
+  // Teleport slot（如需要）
+  const { messageSlotId } = useMessageSlotId();
+
+  // 状态管理
+  const panelVisible = shallowRef(false);
+
+  // 事件处理
+  const handleClick = () => {
+    panelVisible.value = !panelVisible.value;
+  };
+
+  // 生命周期
+  onMounted(() => {
+    // 初始化逻辑
+  });
+
+  onUnmounted(() => {
+    // 清理资源
+  });
+</script>
+
+<style lang="scss">
+  .{role}-message {
+    display: flex;
+    flex-direction: column;
+
+    &-content {
+      display: flex;
+      padding: 16px;
+      background-color: #f5f7fa;
+      border-radius: 8px;
+    }
+
+    &-panel {
+      padding: 24px;
+      background: #fff;
+      border-radius: 8px;
+      box-shadow: 0 2px 12px rgba(0, 0, 0, 0.1);
+    }
+  }
+</style>
+```
+
+### 单元测试模板
+
+```typescript
+import { mount } from '@vue/test-utils';
+import { describe, expect, it, vi } from 'vitest';
+
+import { MessageStatus } from '@blueking/chat-x';
+
+import {Role}Message from './{role}-message.vue';
+
+// Mock useMessageSlotId
+vi.mock('@blueking/chat-x', async () => {
+  const actual = await vi.importActual('@blueking/chat-x');
+  return {
+    ...actual,
+    useMessageSlotId: () => ({
+      messageSlotId: { value: '#test-slot' },
+    }),
+  };
+});
+
+describe('{Role}Message', () => {
+  const createMessage = (overrides = {}) => ({
+    id: 'test-id',
+    messageId: 'test-message-id',
+    role: '{role}' as const,
+    status: MessageStatus.Complete,
+    content: {
+      // 默认内容
+    },
+    ...overrides,
+  });
+
+  it('应该正确渲染组件', () => {
+    const wrapper = mount({Role}Message, {
+      props: { message: createMessage() },
+    });
+    expect(wrapper.find('.{role}-message').exists()).toBe(true);
+  });
+
+  it('应该正确接收 message props', () => {
+    const message = createMessage();
+    const wrapper = mount({Role}Message, {
+      props: { message },
+    });
+    expect(wrapper.props('message')).toEqual(message);
+  });
+
+  // 添加更多测试用例...
+});
+```
+
+### 集成示例
+
+```vue
+<template>
+  <MessageContainer :messages="messages">
+    <template #default="{ message }">
+      <!-- 自定义消息类型 -->
+      <{Role}Message v-if="message.role === '{role}'" :message="message" />
+      <!-- 内置消息类型 -->
+      <MessageRender
+        v-else
+        :message="message"
+      />
+    </template>
+  </MessageContainer>
+</template>
+
+<script setup lang="ts">
+  import { MessageContainer, MessageRender } from '@blueking/chat-x';
+  import {Role}Message from './components/{role}-message/{role}-message.vue';
+</script>
+```
+
+## 检查清单
+
+生成代码后，确认以下项目：
+
+- [ ] 文件结构正确：`<template>` → `<script setup>` → `<style>`
+- [ ] import 顺序正确：Vue → 第三方 → 本地 → 类型
+- [ ] 使用 `shallowRef` 而非 `ref`
+- [ ] 使用 `useTemplateRef` 获取模板引用
+- [ ] Props 使用 `defineProps<Interface>()` 泛型
+- [ ] 类名使用 BEM 风格
+- [ ] 样式使用 SCSS
+- [ ] 包含单元测试文件
+- [ ] Teleport 使用前检查 `messageSlotId` 是否存在
+- [ ] 组件销毁时清理资源（如 chart.dispose()）