postar-pipe-mcp 0.0.1

package/src/skills/ci/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: ci
+description: 自动化 CI 工作流 - 通过创建并合并 MR 将代码从源分支合并到目标分支，支持可选的 CD 部署。支持单环境合并、多环境批量合并、代码 Review 模式、合并后自动部署。当用户输入 ci、合并、 /ci 指令，或需要合并代码到目标环境时使用。
+constraint: strict
+version: 1.0.0
+---
+
+# CI 自动化工作流
+
+> ⚠️ **执行约束（CRITICAL）- 必须遵守**
+>
+> 1. **必须完整阅读**：在执行任何操作前，必须完整阅读本 Skill 的所有内容
+> 2. **严格按步骤执行**：必须严格按照下文"执行流程"中的步骤顺序执行，严禁跳过任何步骤
+> 3. **仅执行定义的操作**：只能执行本 Skill 中明确定义的操作，严禁执行其他未指定的操作
+> 4. **验证每一步**：每一步完成后必须验证结果，确认成功后再进行下一步
+> 5. **错误处理**：如遇错误必须立即停止执行并报告，严禁擅自绕过或忽略错误
+> 6. **禁止假设**：不要假设任何配置或状态，必须通过工具调用来确认
+> 7. **顺序执行**：多环境部署时必须按顺序逐个执行，严禁并行处理
+
+## 说明
+
+本指令用于自动化代码合并流程，通过创建并合并 GitLab MR 将代码从源分支合并到目标分支。支持单环境合并、多环境批量合并，并可选择是否启用代码 Review 模式。
+
+## 变量配置
+
+| 变量 | 简写 | 默认值 | 说明 |
+|------|------|--------|------|
+| `ENV` | `dev`/`test`/`uat` | `dev` | 目标环境，支持单环境或逗号分隔的多环境，如 `dev,test` |
+| `SOURCE_BRANCH` | `branch:分支名` | 当前分支 | 源分支，使用 `branch:分支名` 格式指定，如 `branch:feature/xxx` |
+| `NEED_REVIEW` | `review` | `false` | 是否需要代码 Review（用户指定 review 时设为 true） |
+| `NEED_DEPLOY` | `/cd`、`发布`、`部署` | `false` | 是否需要部署（命令中包含这些关键词时设为 true） |
+
+
+> **参数解析规则**：
+> 1. 优先匹配简写：`dev`/`test`/`uat`/`review`
+> 2. 匹配 `branch:` 前缀，提取分支名作为 `SOURCE_BRANCH`
+> 3. 若包含 `=` 则按 `KEY=VALUE` 解析
+> 4. **多环境支持**：环境参数支持逗号分隔，如 `dev,test` 表示依次合并到 dev 和 test 环境
+> 5. **部署关键词检测**：若命令中包含 `/cd`、`发布`、`部署` 关键词，设置 `NEED_DEPLOY=true`
+
+### 环境对应分支
+
+分支配置从项目根目录的 `config.yaml` 中读取，支持以下占位符：
+
+| ENV | PERSONAL_BRANCH | TARGET_BRANCH | 说明 |
+|-----|-----------------|---------------|------|
+| `dev` | `{personal_branch_dev}` | `{target_branch_dev}` | 开发环境 |
+| `test` | `{personal_branch_test}` | `{target_branch_test}` | 测试环境 |
+| `uat` | `{personal_branch_uat}` | `{target_branch_uat}` | UAT环境 |
+
+> **注意**：如果某环境的 `PERSONAL_BRANCH` 未配置（为空），则跳过步骤 2，直接执行 SOURCE_BRANCH → TARGET_BRANCH 的合并。
+
+## 公共逻辑定义
+
+### 0. 分支存在性检查逻辑
+
+创建 MR 前执行：
+- 调用 `mcp_gitlab_browse_refs` (action=get_branch, branch={目标分支})
+- 如果返回 404 或分支不存在：**立即停止执行**，输出：
+  ```
+  ❌ 目标分支不存在：{目标分支}
+  请先创建分支 {目标分支} 后重试
+  ```
+
+### 1. MR 状态检查逻辑
+
+创建 MR 后执行：
+- 检查 `merge_status` 字段
+- 如果为 `cannot_be_merged`：
+  1. **检查是否为无文件变更的情况**：比较 `diff_refs.base_sha` 和 `diff_refs.head_sha`
+     - 如果两者相同（无实际文件变更）：
+       - 自动关闭 MR：`mcp_gitlab_manage_merge_request` (action=update, state_event=close)
+       - 输出提示信息：
+         ```
+         ℹ️ MR 无文件变更（已合并过），自动关闭
+         MR 链接: {web_url}
+         ```
+       - **继续执行后续步骤**（视为合并成功）
+     - 如果两者不同（存在实际冲突）：
+       - **立即停止执行**，输出：
+         ```
+         ❌ MR 创建失败：{source_branch} → {target_branch} 存在冲突，无法自动合并
+         MR 链接: {web_url}
+         请手动解决冲突后重试
+         ```
+
+### 2. Review 检查逻辑
+
+当 `NEED_REVIEW` 为 `true` 或用户明确要求 review 时：
+1. **以可点击的 Markdown 链接格式输出 MR 链接**：`[点击查看 MR]({web_url})`
+2. **等待用户确认**：提示用户 "请 Review 代码，确认无误后回复 '继续' 或 '确认合并' 以执行自动合并"
+3. **停止自动执行**：等待用户回复后再继续
+
+### 3. MR 合并逻辑
+
+执行 `mcp_gitlab_manage_merge_request` (action=merge)：
+- `merge_when_pipeline_succeeds: true`
+- 如果失败（如 405 错误）：**立即停止执行**，输出：
+  ```
+  ❌ MR 合并失败：{error_message}
+  MR 链接: {web_url}
+  请检查 MR 状态后手动处理
+  ```
+
+## 执行流程
+
+### 前置检查: GitLab MCP 可用性验证
+
+在执行任何步骤前，必须先完成以下验证，**验证通过后才能继续，否则立即停止**：
+
+1. 调用只读工具 `mcp_gitlab_browse_projects`（action=list, per_page=1）
+2. **判断结果**：
+   - 如果返回 `tool not found` 或 `not found MCPHost` 或 `50001` 错误码：**立即停止，禁止执行后续任何步骤**，输出：
+     ```
+     ❌ GitLab MCP 不可用，无法执行自动化 CI 流程
+     请在 MCP 配置中启用 GitLab MCP 后重试：
+     编辑器设置 → MCP → 启用 GitLab
+     ```
+   - 如果返回其他任何结果（含 404、401、数据等）：视为 MCP 可用，继续执行
+
+### 步骤 1: 获取分支信息
+
+> **⚠️ 必须每次重新读取 `config.yaml`**：禁止使用上下文缓存，每次执行 `/ci` 时都要重新读取项目根目录的 `config.yaml` 文件，提取所有相关配置（分支映射、MR 标题模板、默认值等）。
+
+1. **解析 SOURCE_BRANCH（源分支）和项目路径**：
+   - 若用户传入了 `branch:分支名`，直接使用该分支作为 SOURCE_BRANCH
+   - 若 `config.yaml` 中配置了 `projects.url`，从 URL 中解析项目路径
+   - **若以上两者都未满足**，合并执行以下命令（一次终端调用获取全部信息）：
+     执行 `git branch --show-current && git remote get-url origin`，解析项目路径（如 zhangkr/ai-test）
+     - 第一行输出作为 SOURCE_BRANCH
+     - 第二行输出解析为项目路径
+
+2. **解析其他配置**：
+   - **ENV**：若用户传入了 `dev`、`test` 或 `uat`，则使用传入值；否则默认 `dev`
+     - **多环境支持**：支持逗号分隔的多环境，如 `dev,test`、`test,uat` 或 `dev,test,uat`
+     - 多环境模式下，按顺序依次执行每个环境的合并流程
+   - **PERSONAL_BRANCH / TARGET_BRANCH**：从 `config.yaml` 中根据 ENV 提取对应值
+
+### 步骤 2: 创建并合并 MR {SOURCE_BRANCH} 到 {PERSONAL_BRANCH}
+
+> **条件判断**：满足以下任一条件时**跳过本步骤**，直接进入步骤 3：
+> 1. `PERSONAL_BRANCH` 未配置（为空）
+> 2. `SOURCE_BRANCH` 与 `PERSONAL_BRANCH` 相同（当前分支就是中转分支，无需自我合并）
+
+1. **执行【分支存在性检查逻辑】**（目标分支：{PERSONAL_BRANCH}）
+
+2. **创建 MR**：`mcp_gitlab_manage_merge_request` (action=create)
+   - source_branch: {SOURCE_BRANCH}
+   - target_branch: {PERSONAL_BRANCH}
+   - title: `{mr_title_template}`（模板变量：{source_branch}, {target_branch}）
+
+3. **执行【MR 状态检查逻辑】**
+
+4. **执行【Review 检查逻辑】**（如果启用 Review 模式）
+
+5. **执行【MR 合并逻辑】**
+
+### 步骤 3: 创建并合并 MR 到 {TARGET_BRANCH}
+
+> **source_branch 取值**：
+> - 如果步骤 2 已执行（`PERSONAL_BRANCH` 已配置且 `SOURCE_BRANCH ≠ PERSONAL_BRANCH`）：使用 `{PERSONAL_BRANCH}`
+> - 如果步骤 2 被跳过（`PERSONAL_BRANCH` 未配置，或 `SOURCE_BRANCH === PERSONAL_BRANCH`）：使用 `{SOURCE_BRANCH}`
+
+1. **执行【分支存在性检查逻辑】**（目标分支：{TARGET_BRANCH}）
+
+2. **创建 MR**：`mcp_gitlab_manage_merge_request` (action=create)
+   - source_branch: 根据上述规则确定
+   - target_branch: {TARGET_BRANCH}
+   - title: `{mr_title_template}`（模板变量：{source_branch}, {target_branch}）
+
+3. **执行【MR 状态检查逻辑】**
+
+4. **执行【Review 检查逻辑】**（如果启用 Review 模式）
+
+5. **执行【MR 合并逻辑】**
+
+### 步骤 4: 验证与完成
+
+#### 单环境模式
+
+- 如果 `PERSONAL_BRANCH` 已配置：确认两个 MR 状态为 merged
+- 如果 `PERSONAL_BRANCH` 未配置：确认 SOURCE_BRANCH → TARGET_BRANCH 的 MR 状态为 merged
+- 确认 {TARGET_BRANCH} 分支已更新
+- 输出 CI 完成信息：
+  ```
+  ✅ CI 流程完成
+
+  📋 合并汇总：
+     源分支: {SOURCE_BRANCH}
+     目标分支: {TARGET_BRANCH}
+     MR 状态: merged
+
+  💡 如需部署，请执行：
+     /cd {ENV}                    # 部署当前分支
+     /cd {ENV} branch:xxx         # 部署指定分支
+  ```
+
+#### 多环境模式
+
+当指定多个环境（如 `dev,test`）时：
+- 按环境顺序依次执行步骤 2 和步骤 3
+- 每个环境独立执行完整的合并流程
+- 前一个环境合并成功后，继续下一个环境
+- 任一环境合并失败，立即停止执行
+
+### 步骤 5: 执行 CD 部署（可选）
+
+> **条件判断**：当 `NEED_DEPLOY=true`（命令中包含 `/cd`、`发布`、`部署` 关键词）时执行此步骤。
+
+1. **读取 CD skill 文件**（跨平台路径查找策略）：
+   - 首先尝试项目级别路径：`.qoder/skills/cd/SKILL.md`（或编辑器对应的 skills 目录）
+   - 如果找不到，则根据操作系统尝试对应的用户级别路径：
+   
+   **macOS/Linux 系统**：
+   - 用户级别路径：`$HOME/.qoder/skills/cd/SKILL.md`（或编辑器配置目录）
+   
+   **Windows 系统**：
+   - 用户级别路径：`%USERPROFILE%\.qoder\skills\cd\SKILL.md`
+   
+   - 实现方式：
+     ```
+     # 项目级别（相对路径，通用）
+     read_file(".qoder/skills/cd/SKILL.md")
+     
+     # macOS/Linux 用户级别
+     read_file("$HOME/.qoder/skills/cd/SKILL.md")
+     
+     # Windows 用户级别
+     read_file("%USERPROFILE%\.qoder\skills\cd\SKILL.md")
+     ```
+
+2. **按照 CD skill 的规范执行部署流程**：
+   - 执行 Jenkins MCP 可用性验证
+   - 读取 `config.yaml` 中的 Jenkins 配置
+   - 使用 `mcp_jenkins_build_item` 触发构建
+   - **⚠️ 关键：`build_type` 必须为 `buildWithParameters`**
+
+3. **多环境部署**：按环境顺序逐个触发，记录每个环境的队列 ID
+
+4. **输出部署结果**（参考 CD skill 的输出格式）
+
+### 步骤 6: 输出最终汇总
+
+**仅 CI 模式**（NEED_DEPLOY=false）：
+```
+✅ CI 流程完成
+
+📋 合并汇总：
+   源分支: {SOURCE_BRANCH}
+   目标分支: {TARGET_BRANCH}
+   MR 状态: merged
+   MR 链接: ({url})
+
+💡 如需部署，请执行：
+   /cd {ENV}                    # 部署当前分支
+   /cd {ENV} branch:xxx         # 部署指定分支
+```
+
+**CI+CD 模式**（NEED_DEPLOY=true）：
+```
+✅ CI/CD 流程完成
+
+📋 合并汇总：
+   源分支: {SOURCE_BRANCH}
+   目标分支: {TARGET_BRANCH}
+   MR 状态: merged
+   MR 链接: ({url})
+
+
+📋 部署汇总：
+   环境: {ENV}
+   Jenkins 队列 ID: {queue_id}
+   🔗 [查看构建进度]({url})
+```
+
+## 使用示例
+
+### 单环境流程（默认）
+
+```
+/ci                           # 默认 dev 环境，使用当前分支作为 SOURCE_BRANCH
+/ci dev                       # 指定 dev 环境（简写）
+/ci ENV=dev                   # 指定 dev 环境（完整写法）
+/ci test review               # test 环境 + 需要 Review
+/ci branch:feature/xxx          # 指定源分支为 feature/xxx
+/ci test branch:bugfix/123      # test 环境 + 指定源分支
+```
+
+执行：SOURCE_BRANCH → PERSONAL_BRANCH → TARGET_BRANCH
+
+### CI + CD 一体化流程
+
+```
+/ci dev,test 发布                 # 合并到 dev 和 test，并部署
+/ci dev /cd                        # 合并到 dev，并部署
+/ci dev,test 并且发布到dev和test    # 合并到 dev 和 test，并部署
+```
+
+执行流程：
+1. CI: SOURCE_BRANCH → dev:TARGET_BRANCH → test:TARGET_BRANCH
+2. CD: 触发 dev 和 test 环境的 Jenkins 构建
+
+### 多环境批量合并
+
+```
+/ci dev,test                    # 依次合并到 dev 和 test 环境
+/ci test,uat                    # 依次合并到 test 和 uat 环境
+/ci dev,test,uat                # 依次合并到 dev、test 和 uat 环境
+/ci dev,test review             # 多环境合并 + 需要 Review
+/ci dev,test branch:feature/xxx # 多环境合并 + 指定源分支
+```
+
+执行流程：
+1. SOURCE_BRANCH → dev:PERSONAL_BRANCH → dev:TARGET_BRANCH
+2. SOURCE_BRANCH → test:PERSONAL_BRANCH → test:TARGET_BRANCH
+
+> **简写规则**：
+> - `dev`/`test`/`uat` 直接指定环境，支持逗号分隔多环境
+> - `review` 等价于 `NEED_REVIEW=true`
+> - `branch:分支名` 指定 `SOURCE_BRANCH`
+> - **多环境顺序**：按参数中指定的顺序依次执行，如 `test,dev` 会先合并到 test 再合并到 dev
+
+## 与 `/cd` 命令的关系
+
+| 命令 | 职责 | 使用场景 |
+|------|------|----------|
+| `/ci` | 代码合并（可选部署） | 需要合并代码到目标分支 |
+| `/cd` | 部署触发（Jenkins 构建） | 仅需部署，无需合并 |
+| `/ci ... 发布` | 合并 + 部署一体化 | 合并后立即部署 |
+
+**典型工作流**：
+```bash
+# 方式1：分步执行
+/ci dev          # 合并代码
+/cd dev          # 部署服务
+
+# 方式2：一体化执行
+/ci dev 发布      # 合并 + 部署一步完成
+```