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

package/knowledge/skills/bk-monitor-tapd-dev/references/branch-workflow.md

@@ -0,0 +1,167 @@
+# 分支管理工作流
+
+## 获取 TAPD ID
+
+按以下优先级获取 TAPD ID：
+
+**方式一：用户直接提供**
+
+如果用户直接提供了 TAPD ID 或 TAPD 链接，解析并使用。
+
+**链接格式解析：**
+
+- 需求详情页：`https://tapd.woa.com/tapd_fe/{workspace_id}/story/detail/{story_id}`
+- 缺陷详情页：`https://tapd.woa.com/tapd_fe/{workspace_id}/bug/detail/{bug_id}`
+- 任务详情页：`https://tapd.woa.com/tapd_fe/{workspace_id}/task/detail/{task_id}`
+
+**方式二：从 Git 分支提取**
+
+如果用户未提供，从当前分支名中提取：
+
+```bash
+git branch --show-current
+```
+
+**匹配规则**：使用正则 `#(\d+)` 提取 ID
+
+**示例**：
+
+- `feat/ai/#1010158081130505269` → TAPD ID: `1010158081130505269`
+- `fix/bug/#1010158081130505270` → TAPD ID: `1010158081130505270`
+
+## 验证分支匹配
+
+获取 TAPD ID 后，**必须检查当前分支是否包含该 ID**：
+
+```bash
+git branch --show-current
+```
+
+**判断逻辑（决策树）：**
+
+```
+用户提供了 TAPD ID？
+├── 是 → 检查当前分支是否包含该 ID
+│   ├── 包含 → ✅ 直接继续后续流程（Step 2）
+│   └── 不包含 → ⛔ 暂停！询问用户选择（等待用户回复后再继续）
+│       ├── 用户选择"创建分支" → 进入 Step 1.3，完成后继续 Step 2
+│       └── 用户选择"继续开发" → 继续 Step 2（用户自行承担风险）
+│
+└── 否 → 从当前分支提取 TAPD ID
+    ├── 提取成功 → ✅ 直接继续后续流程（Step 2）
+    └── 提取失败 → ⛔ 暂停！询问用户提供 TAPD ID（等待用户回复）
+```
+
+> ⚠️ **必须等待用户选择后才能继续**，不要在用户回复前执行任何后续步骤！
+
+## 分支命名规则
+
+`{type}/{category}/#{TAPD_ID}`
+
+| 单据类型      | type   | 示例分支名                       |
+| ------------- | ------ | -------------------------------- |
+| 需求（Story） | `feat` | `feat/opus/#1010158081130072997` |
+| 缺陷（Bug）   | `fix`  | `fix/opus/#1010158081130072997`  |
+| 任务（Task）  | `task` | `task/opus/#1010158081130072997` |
+
+## category 取值规则
+
+使用当前 AI 模型缩写作为 category：
+
+| 模型              | category   |
+| ----------------- | ---------- |
+| Claude Opus 4.5   | `opus`     |
+| Claude Sonnet 4   | `sonnet`   |
+| Claude 3.5 Sonnet | `sonnet35` |
+| GPT-4             | `gpt4`     |
+| 其他/未知         | `ai`       |
+
+## 创建分支命令
+
+```bash
+# Step 1: 同步 upstream 仓库最新代码
+git fetch upstream
+
+# Step 2: 基于 upstream/master 创建新分支
+git checkout -b {type}/{category}/#{TAPD_ID} upstream/master
+
+# Step 3: 推送分支到 origin 仓库
+git push --set-upstream origin {type}/{category}/#{TAPD_ID}
+```
+
+## 分支不匹配时的询问模板
+
+使用 AskQuestion 工具：
+
+```
+⚠️ 分支不匹配
+
+当前分支：`{当前分支名}`
+目标 TAPD ID：`{用户提供的 TAPD ID}`
+
+当前分支不包含目标 TAPD ID，请选择操作方式：
+```
+
+**选项：**
+
+1. **创建新分支**：使用 Git 命令创建包含此 TAPD ID 的新分支
+2. **继续开发**：在当前分支继续开发（不推荐，可能导致代码混乱）
+
+## 创建分支时的类型询问
+
+由于此时还未获取单据详情，无法确定单据类型。使用 AskQuestion 工具询问用户：
+
+```
+📌 创建分支
+
+TAPD ID：`{TAPD_ID}`
+
+请选择单据类型以确定分支前缀：
+```
+
+**选项：**
+
+1. **需求（feat）**：创建 `feat/{category}/#{TAPD_ID}` 分支
+2. **缺陷（fix）**：创建 `fix/{category}/#{TAPD_ID}` 分支
+3. **任务（task）**：创建 `task/{category}/#{TAPD_ID}` 分支
+
+**用户选择后执行命令：**
+
+1. 依次执行上述 Git 命令（需要 `git_write` 和 `network` 权限）
+2. 验证分支创建成功
+
+**验证分支：**
+
+```bash
+git branch --show-current
+```
+
+**验证逻辑：**
+
+- 如果新分支包含目标 TAPD ID → ✅ 继续 Step 2
+- 如果分支创建失败 → 输出错误信息，询问用户如何处理
+
+## TAPD ID 解析
+
+TAPD ID 是 19 位数字：`10` + `workspace_id(8位)` + `序列号(9位)`
+
+| 完整 ID               | workspace_id |
+| --------------------- | ------------ |
+| `1010158081130505269` | `10158081`   |
+
+解析代码：`workspace_id = id.substring(2, 10)`
+
+## Workspace 名称映射
+
+| workspace_id | 项目名       |
+| ------------ | ------------ |
+| 10158081     | 蓝鲸监控     |
+| 70093903     | 蓝鲸开发工具 |
+
+## TAPD 链接格式
+
+| 类型 | 链接格式                                                        |
+| ---- | --------------------------------------------------------------- |
+| 需求 | `https://tapd.woa.com/tapd_fe/{workspace_id}/story/detail/{id}` |
+| 缺陷 | `https://tapd.woa.com/tapd_fe/{workspace_id}/bug/detail/{id}`   |
+| 任务 | `https://tapd.woa.com/tapd_fe/{workspace_id}/task/detail/{id}`  |

package/knowledge/skills/bk-monitor-tapd-dev/references/dev-plan-template.md

@@ -0,0 +1,85 @@
+# 开发方案模板
+
+## 输出格式
+
+```markdown
+# 开发方案
+
+## 单据信息
+
+| 字段     | 内容                |
+| -------- | ------------------- |
+| 类型     | 需求/缺陷/任务      |
+| ID       | {TAPD_ID}           |
+| 标题     | {标题}              |
+| 优先级   | {优先级}            |
+| 状态     | {状态}              |
+| 截止日期 | {截止日期}          |
+| 链接     | [TAPD 详情]({link}) |
+
+## 评论摘要
+
+> 关键讨论和需求变更记录
+
+## 需求分析
+
+### 功能需求
+
+1. 需求点 1
+2. 需求点 2
+
+### 验收标准
+
+- [ ] 验收项 1
+- [ ] 验收项 2
+
+## 技术方案
+
+### 目标模块
+
+{模块名称} (Vue2/Vue3)
+
+### 组件设计
+
+```
+{组件目录结构}
+```
+
+### API 调用
+
+| 接口       | 方法 | 路径        | 说明     |
+| ---------- | ---- | ----------- | -------- |
+| {接口名称} | POST | /rest/v1/xx | {接口说明} |
+
+### 路由配置（如需要）
+
+```typescript
+{
+  path: '/xxx',
+  name: 'xxx',
+  component: () => import('./xxx.vue'),
+}
+```
+
+## 开发步骤
+
+1. [ ] 创建组件文件结构
+2. [ ] 实现核心功能
+3. [ ] 添加样式
+4. [ ] 配置路由（如需要）
+5. [ ] 联调测试
+
+## 注意事项
+
+- 注意事项 1
+- 注意事项 2
+```
+
+## 开发规范
+
+- Vue2 组件使用 `vue-property-decorator` + `vue-tsx-support`
+- Vue3 组件使用 `defineComponent`
+- 文件名使用 kebab-case
+- 组件名使用 PascalCase
+- SCSS 类名使用 kebab-case
+- 遇到不确定的问题主动询问用户

package/knowledge/skills/bk-monitor-tapd-dev/references/mcp-calls.md

@@ -0,0 +1,157 @@
+# TAPD MCP 调用详情
+
+## Step 3: 获取单据详情
+
+由于无法从 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",
+    "fields": "id,name,description,status,v_status,priority,priority_label,owner,creator,due,iteration_id,workspace_id"
+  }
+}
+
+// 并行调用 2: 查询缺陷
+{
+  "tool_name": "bugs_get",
+  "tool_args": {
+    "workspace_id": "<解析出的workspace_id>",
+    "id": "<完整的19位ID>",
+    "fields": "id,title,description,status,priority,priority_label,severity,current_owner,reporter,due,iteration_id,workspace_id"
+  }
+}
+
+// 并行调用 3: 查询任务
+{
+  "tool_name": "tasks_get",
+  "tool_args": {
+    "workspace_id": "<解析出的workspace_id>",
+    "id": "<完整的19位ID>",
+    "fields": "id,name,description,status,priority,priority_label,owner,creator,due,story_id,iteration_id,workspace_id"
+  }
+}
+```
+
+从返回有效数据的接口中提取单据信息，并记录单据类型（story/bug/task）。
+
+## Step 3.5: 获取单据评论
+
+**重要**：评论中通常包含产品/开发/测试之间的沟通细节，对理解需求至关重要。
+
+根据 Step 3 确定的单据类型，调用评论接口：
+
+```json
+// 调用 MCP: user-tapd_mcp_http
+// 工具: proxy_execute_tool
+
+{
+  "tool_name": "comments_get",
+  "tool_args": {
+    "workspace_id": "<解析出的workspace_id>",
+    "entry_type": "<单据类型>",
+    "entry_id": "<完整的19位ID>",
+    "limit": 50
+  }
+}
+```
+
+**entry_type 映射规则**：
+
+| 单据类型      | entry_type |
+| ------------- | ---------- |
+| 需求（Story） | `stories`  |
+| 缺陷（Bug）   | `bug`      |
+| 任务（Task）  | `tasks`    |
+
+**评论信息提取**：
+
+- 补充说明：对需求描述的补充或澄清
+- 需求变更：对原始需求的修改或调整
+- 技术讨论：开发方案的讨论和决策
+- 设计稿/文档链接：评论中附带的设计资源
+
+## Step 4: 分析开发需求
+
+根据**单据内容**和**评论信息**综合分析开发需求：
+
+### 4.1 从单据中提取
+
+- **标题**：需求/缺陷/任务名称
+- **描述**：详细描述内容（可能包含 HTML）
+- **优先级**：紧急/高/中/低
+- **状态**：当前状态
+- **截止日期**：预期完成时间
+
+### 4.2 从评论中提取
+
+- **补充说明**：对原始描述的补充
+- **需求变更**：评论中提到的需求调整
+- **最终结论**：讨论后达成的共识
+
+### 4.3 分析描述内容
+
+解析描述中的：
+
+- 功能需求点
+- UI/UX 设计稿链接
+- 相关文档链接
+- 验收标准
+
+**结合评论内容**：
+
+- 检查评论中是否有对描述的补充或修正
+- 如果评论与描述有冲突，以最新评论为准
+- 提取评论中的关键决策和结论
+
+### 4.4 结合项目上下文
+
+参考项目最佳实践（`wikis/contributes.md`）：
+
+- 确定目标模块（monitor-pc/trace/apm 等）
+- 确定技术栈（Vue2/Vue3）
+- 确定组件规范
+
+## Step 6: 确认并执行开发
+
+### 6.1 等待用户确认
+
+输出方案后，询问用户：
+
+```
+以上是根据 TAPD 单据生成的开发方案，请确认：
+
+1. 需求分析是否准确？
+2. 技术方案是否合理？
+3. 开发步骤是否完整？
+
+如有需要修改的地方，请告诉我。
+
+确认无误后，请回复 **"开始开发"** 或 **"确认"**，我将按照方案进行开发。
+```
+
+### 6.2 执行开发
+
+用户确认后，按照开发步骤逐步实现：
+
+1. **创建文件结构**：按照组件设计创建文件
+2. **实现组件代码**：遵循项目规范（参考 `wikis/contributes.md`）
+3. **添加样式文件**：创建对应的 SCSS 文件
+4. **配置路由**：如需要，添加路由配置
+5. **调用 API**：实现 API 调用逻辑
+
+**开发过程中遵循的规范**：
+
+- Vue2 组件使用 `vue-property-decorator` + `vue-tsx-support`
+- Vue3 组件使用 `defineComponent`
+- 文件名使用 kebab-case
+- 组件名使用 PascalCase
+- SCSS 类名使用 kebab-case
+- 遇到不确定的问题主动询问用户

package/knowledge/skills/bk-monitor-tapd-dev/references/tapd-mcp-guide.md

@@ -0,0 +1,284 @@
+# TAPD MCP 使用指南
+
+本文档总结 TAPD ID 解析规则和 TAPD MCP 工具的使用方法。
+
+## TAPD ID 结构解析
+
+### ID 格式
+
+TAPD ID 是 **19 位数字**，由三部分组成：
+
+```
+前缀(2位) + workspace_id(8位) + 序列号(9位)
+```
+
+### 解析规则
+
+| 组成部分 | 位置 | 说明 |
+|---------|------|------|
+| 前缀 | `[0:2]` | 固定为 `10` |
+| workspace_id | `[2:10]` | 项目 ID，8 位数字 |
+| 序列号 | `[10:19]` | 单据序列号，9 位数字 |
+
+### 解析示例
+
+| 完整 TAPD ID | 前缀 | workspace_id | 序列号 |
+|-------------|------|--------------|--------|
+| `1010158081130505269` | `10` | `10158081` | `130505269` |
+| `1070093903123456789` | `10` | `70093903` | `123456789` |
+
+### 解析代码
+
+```javascript
+const tapdId = '1010158081130505269';
+const workspaceId = tapdId.substring(2, 10); // '10158081'
+```
+
+```python
+tapd_id = '1010158081130505269'
+workspace_id = tapd_id[2:10]  # '10158081'
+```
+
+---
+
+## Workspace 名称映射
+
+| workspace_id | 项目名称 |
+|-------------|---------|
+| `10158081` | 蓝鲸监控 |
+| `70093903` | 蓝鲸开发工具 |
+
+---
+
+## TAPD MCP 工具
+
+### MCP 服务器信息
+
+- **Server**: `user-tapd_mcp_http`
+- **执行工具**: `proxy_execute_tool`
+
+### 核心工具列表
+
+#### 查询类工具
+
+| 工具名 | 用途 | 必需参数 |
+|-------|------|---------|
+| `stories_get` | 查询需求列表 | `workspace_id` |
+| `bugs_get` | 查询缺陷列表 | `workspace_id` |
+| `tasks_get` | 查询任务列表 | `workspace_id` |
+| `iterations_get` | 查询迭代列表 | `workspace_id` |
+
+#### 用户待办工具
+
+| 工具名 | 用途 | 说明 |
+|-------|------|------|
+| `user_todo_stories_get` | 获取用户待办需求 | workspace_id 可选 |
+| `user_todo_bugs_get` | 获取用户待办缺陷 | workspace_id 可选 |
+| `user_todo_tasks_get` | 获取用户待办任务 | workspace_id 可选 |
+
+#### 辅助工具
+
+| 工具名 | 用途 |
+|-------|------|
+| `lookup_tapd_tool` | 语义搜索匹配 TAPD 工具 |
+| `stories_fields_info_get` | 获取需求字段配置 |
+| `bugs_fields_info_get` | 获取缺陷字段配置 |
+| `tasks_fields_info_get` | 获取任务字段配置 |
+
+---
+
+## 调用方式
+
+### 基础调用格式
+
+```json
+// 使用 CallMcpTool 调用
+{
+  "server": "user-tapd_mcp_http",
+  "toolName": "proxy_execute_tool",
+  "arguments": {
+    "tool_name": "<目标工具名>",
+    "tool_args": {
+      // 工具参数
+    }
+  }
+}
+```
+
+### 查询单个需求
+
+```json
+{
+  "server": "user-tapd_mcp_http",
+  "toolName": "proxy_execute_tool",
+  "arguments": {
+    "tool_name": "stories_get",
+    "tool_args": {
+      "workspace_id": "10158081",
+      "id": "1010158081130505269",
+      "with_v_status": "1",
+      "fields": "id,name,description,status,v_status,priority,priority_label,owner,due"
+    }
+  }
+}
+```
+
+### 查询单个缺陷
+
+```json
+{
+  "server": "user-tapd_mcp_http",
+  "toolName": "proxy_execute_tool",
+  "arguments": {
+    "tool_name": "bugs_get",
+    "tool_args": {
+      "workspace_id": "10158081",
+      "id": "1010158081130505269",
+      "fields": "id,title,description,status,priority,priority_label,severity,current_owner,due"
+    }
+  }
+}
+```
+
+### 查询单个任务
+
+```json
+{
+  "server": "user-tapd_mcp_http",
+  "toolName": "proxy_execute_tool",
+  "arguments": {
+    "tool_name": "tasks_get",
+    "tool_args": {
+      "workspace_id": "10158081",
+      "id": "1010158081130505269",
+      "fields": "id,name,description,status,priority,priority_label,owner,due"
+    }
+  }
+}
+```
+
+### 查询用户待办需求（按状态筛选）
+
+```json
+{
+  "server": "user-tapd_mcp_http",
+  "toolName": "proxy_execute_tool",
+  "arguments": {
+    "tool_name": "stories_get",
+    "tool_args": {
+      "workspace_id": "10158081",
+      "owner": "liangling",
+      "status": "planning|developing|status_7",
+      "with_v_status": "1",
+      "limit": 30,
+      "fields": "id,name,owner,due,priority,priority_label,status,v_status,workspace_id"
+    }
+  }
+}
+```
+
+---
+
+## 常用字段说明
+
+### 需求（Story）字段
+
+| 字段 | 说明 |
+|------|------|
+| `id` | 需求 ID（19 位） |
+| `name` | 需求标题 |
+| `description` | 详细描述（HTML 格式） |
+| `status` | 状态（英文代码） |
+| `v_status` | 状态（中文名称） |
+| `priority` | 优先级代码 |
+| `priority_label` | 优先级标签（High/Middle/Low） |
+| `owner` | 处理人 |
+| `creator` | 创建人 |
+| `due` | 截止日期 |
+| `iteration_id` | 迭代 ID |
+| `workspace_id` | 项目 ID |
+
+### 缺陷（Bug）字段
+
+| 字段 | 说明 |
+|------|------|
+| `id` | 缺陷 ID（19 位） |
+| `title` | 缺陷标题 |
+| `description` | 详细描述（HTML 格式） |
+| `status` | 状态 |
+| `priority` | 优先级 |
+| `priority_label` | 优先级标签 |
+| `severity` | 严重程度 |
+| `current_owner` | 当前处理人 |
+| `reporter` | 报告人 |
+| `due` | 截止日期 |
+
+### 任务（Task）字段
+
+| 字段 | 说明 |
+|------|------|
+| `id` | 任务 ID（19 位） |
+| `name` | 任务标题 |
+| `description` | 详细描述 |
+| `status` | 状态（open/progressing/done） |
+| `priority` | 优先级 |
+| `priority_label` | 优先级标签 |
+| `owner` | 处理人 |
+| `creator` | 创建人 |
+| `due` | 截止日期 |
+| `story_id` | 关联需求 ID |
+
+---
+
+## TAPD 链接格式
+
+### 生成链接
+
+| 单据类型 | 链接格式 |
+|---------|---------|
+| 需求 | `https://tapd.woa.com/tapd_fe/{workspace_id}/story/detail/{id}` |
+| 缺陷 | `https://tapd.woa.com/tapd_fe/{workspace_id}/bug/detail/{id}` |
+| 任务 | `https://tapd.woa.com/tapd_fe/{workspace_id}/task/detail/{id}` |
+
+### 链接示例
+
+```
+需求：https://tapd.woa.com/tapd_fe/10158081/story/detail/1010158081130505269
+缺陷：https://tapd.woa.com/tapd_fe/10158081/bug/detail/1010158081130505269
+任务：https://tapd.woa.com/tapd_fe/10158081/task/detail/1010158081130505269
+```
+
+---
+
+## 工具发现
+
+如果不确定使用哪个工具，可以使用 `lookup_tapd_tool` 进行语义搜索：
+
+```json
+{
+  "server": "user-tapd_mcp_http",
+  "toolName": "lookup_tapd_tool",
+  "arguments": {
+    "task_description": "查询需求详情",
+    "top_k": 5
+  }
+}
+```
+
+**注意**：`task_description` 应使用提炼后的"动作+对象"格式，而非用户原话。
+
+| 用户原话 | 提炼后（传入参数） |
+|---------|-------------------|
+| "帮我看看项目里有哪些 bug" | "查询缺陷列表" |
+| "我想提一个新的需求" | "创建需求" |
+| "修改一下这个 story 的状态" | "更新需求状态" |
+
+---
+
+## 注意事项
+
+1. **ID 类型判断**：无法从 TAPD ID 本身判断是需求/缺陷/任务，需要并行调用三个接口
+2. **字段限制**：使用 `fields` 参数限制返回字段，减少数据量
+3. **分页查询**：使用 `limit` 和 `page` 参数进行分页
+4. **状态筛选**：使用 `status` 参数筛选特定状态，多个状态用 `|` 分隔
+5. **中文状态**：需求查询时设置 `with_v_status: "1"` 可返回中文状态名