165 lines
8.6 KiB
Markdown
165 lines
8.6 KiB
Markdown
---
|
||
name: g3fo-commit-jira
|
||
description: G3FO 项目 Git 提交规范自动化工具。强制要求提供 git 修订号（hash），支持用户直接提供 Jira 编号或自动查找/创建 Jira 任务。按任务类型（漏洞修复/新功能/重构等）判定需附加的文档（开发计划、影响分析、任务摘要），生成对应 MD 并按公司规范命名（<JIRA-ID>_Dev_Plan.md / _Impact_Analysis.md / _Task_Summary.md）上传到 Jira 附件，将影响分析写入评论，最后将 Jira 编号追加到 commit message 末尾后提交（不 push）。适用于 G3FO/G3SF 项目的所有 git 提交场景。
|
||
---
|
||
|
||
# G3FO Commit Jira 技能
|
||
|
||
本技能通过 git 修订号自动分析改动，绑定/创建 Jira 任务，按**公司 Jira 工单附件文档政策**生成并上传所需文档（开发计划、影响分析、任务摘要），并更新 commit message。
|
||
|
||
> **公司文档政策**（自 2026-03-09 起）：何时附加哪些文件见 `references/jira_commit_docs_policy.md`。
|
||
> 报告模板、任务类型判定与 JQL 参考 `references/workflow.md`。
|
||
|
||
---
|
||
|
||
## 前置要求
|
||
|
||
**1. 强制提供 Git 修订号 (hash)**
|
||
|
||
用户必须提供一个有效的 git 修订号（如 `HEAD` 或具体的 `hash`）。
|
||
- **校验逻辑**：使用 `git rev-parse <hash>` 检查修订号是否存在。
|
||
- **错误处理**：如果修订号无效或找不到，**必须** 停止操作并提示用户：“找不到修订号 `<hash>`，请提供正确的 git 修订号（例如 HEAD 或 7 位以上的 commit hash）。”
|
||
- **路径要求**：必须在相关的项目根目录下执行 git 命令。如果当前目录不是 git 仓库或不是目标项目，请提示用户切换到正确的项目路径。
|
||
|
||
**2. Jira 编号 (可选)**
|
||
|
||
用户可以主动提供 Jira 编号（如 `G3SF-123`）。
|
||
- 如果提供了 Jira 编号，直接引用该编号，跳过“查找/选择 Jira 任务”的步骤。
|
||
- 如果未提供，则按流程自动查找或提示用户新建。
|
||
|
||
**3. Atlassian MCP 授权**
|
||
|
||
- 查看 `mcps/plugin-atlassian-atlassian/STATUS.md` 确认已在 Cursor 中授权 MCP 插件。
|
||
- 如果未授权，调用 `mcp_auth`，server: `plugin-atlassian-atlassian`，参数 `{}`。
|
||
- 若 MCP 插件未安装，引导用户按以下步骤操作：
|
||
1. 打开 Cursor Settings -> MCP
|
||
2. 添加名为 `Atlassian` 的插件
|
||
3. 按照提示完成授权并启用 skill
|
||
- 确保可用工具在 `mcps/plugin-atlassian-atlassian/tools/` 目录下已列出。
|
||
|
||
**4. 上传附件配置（用于将影响分析报告 MD 上传到 Jira）**
|
||
|
||
- Atlassian MCP 插件不支持上传文件，本技能使用自带脚本 `scripts/upload_attachment.py` 将报告 MD 上传为 Issue 附件。
|
||
- 在技能目录或脚本目录放置 `jira_upload.env`（或使用 `--config` 指定路径），包含：`JIRA_BASE_URL`、`JIRA_EMAIL`、`JIRA_API_TOKEN`。格式见 `jira_upload.env.example`，详细说明见 `references/env_config.md`。
|
||
- 若未配置，上传附件步骤跳过，仅通过 `jira_add_comment` 写入报告；已配置则先上传 MD 再写评论。
|
||
|
||
---
|
||
|
||
## 执行步骤
|
||
|
||
### Step 1 - 获取提交内容
|
||
|
||
```powershell
|
||
git show <hash> # 获取 diff + 元数据
|
||
git log -1 --format="%B" <hash> # 获取原始 commit message
|
||
```
|
||
|
||
分析要点：
|
||
- 涉及的服务模块/包名
|
||
- 新增/修改/删除的方法与接口
|
||
- 逻辑改动的核心目的
|
||
|
||
### Step 2 - 判定任务类型并确定需生成的文档
|
||
|
||
根据改动内容与 `references/jira_commit_docs_policy.md` 中的**详细条件表**，先判定任务类型，再决定需要生成并上传的文档：
|
||
|
||
| 任务类型 | 开发计划 | 影响分析 | 任务摘要 |
|
||
|----------|:--------:|:--------:|:--------:|
|
||
| 漏洞修复——简单（如拼写、界面对齐） | ❌ | ❌ | ❌ |
|
||
| 漏洞修复——中等（范围有限的逻辑错误） | ❌ | ✅ | ❌ |
|
||
| 漏洞修复——复杂/高风险（并发、核心模块） | ✅ | ✅ | ✅ |
|
||
| 小幅度增强（如小效用方法） | ❌ | ✅ | ❌ |
|
||
| 新功能/模块 | ✅ | ✅ | ✅ |
|
||
| 主要重构 | ✅ | ✅ | ✅ |
|
||
| 配置/基础设施变更 | ❌ | ✅ | ❌ |
|
||
|
||
- **无需任何文档**时：仅执行 Step 3（确定 Jira）、Step 5（amend），不生成报告、不写评论、不上传附件；仍将 Jira 编号追加到 commit message。
|
||
- **需要文档**时：继续 Step 2 下半部分，生成对应内容。
|
||
|
||
### Step 2（续）- 生成所需报告内容
|
||
|
||
对上述判定为“需要”的文档，按 `references/workflow.md` 中的模板生成内容（可先存于内存或临时文件）：
|
||
|
||
- **开发计划**：步骤、设计方法、技术决策。
|
||
- **影响分析**：改动概览、方法级分析、影响范围、风险与回滚、验证与测试（模板见 workflow.md）。
|
||
- **任务摘要**：所完成工作的简要回顾，以及任何偏离计划之处。
|
||
|
||
生成后先不按“公司附件名”落盘，等取得 Jira 编号后再以 `<JIRA-ID>_*.md` 命名保存并上传。
|
||
|
||
### Step 3 - 确定 Jira 任务
|
||
|
||
**1. 如果用户已提供 Jira 编号：**
|
||
- 直接使用该编号（如 `G3SF-123`），进入 Step 4。
|
||
|
||
**2. 如果用户未提供 Jira 编号：**
|
||
- 使用 JQL 查找当前用户在 G3SF 项目下的进行中任务（limit 5）：
|
||
```
|
||
project = G3SF AND assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC
|
||
```
|
||
- 展示列表供用户选择，或允许用户输入 `0` 新建。
|
||
- 如果搜索结果为空，自动进入新建流程。
|
||
|
||
### Step 4 - 写入 Jira（附件 + 评论）
|
||
|
||
**附件命名规范（公司要求）**：上传到 Jira 的 MD 文件名必须为
|
||
`<JIRA-ID>_Dev_Plan.md`、`<JIRA-ID>_Impact_Analysis.md`、`<JIRA-ID>_Task_Summary.md`。
|
||
根据 Step 2 判定结果，仅上传“需要”的文档；每个文件先按该命名写入本地再上传（脚本以本地文件名为 Jira 附件名）。
|
||
|
||
**如果选择/新建的任务 ID > 0：**
|
||
|
||
1. **保存并上传附件**（已配置 `jira_upload.env` 且本任务需要文档时）：
|
||
将 Step 2 生成的各文档内容，按公司规范命名写入当前项目目录（或 `docs/` 等），再调用上传脚本。PowerShell 中不要用 `&&`，改用 `;` 或换行。
|
||
|
||
```powershell
|
||
# 示例：需要三份文档时，先写入 G3SF-123_Dev_Plan.md、G3SF-123_Impact_Analysis.md、G3SF-123_Task_Summary.md，再：
|
||
python skills/g3fo-commit-jira/scripts/upload_attachment.py --config "skills/g3fo-commit-jira/jira_upload.env" --issue "G3SF-123" --file "G3SF-123_Impact_Analysis.md" --file "G3SF-123_Dev_Plan.md" --file "G3SF-123_Task_Summary.md"
|
||
```
|
||
|
||
若本任务仅需影响分析，则只写入并上传 `G3SF-123_Impact_Analysis.md`。未配置 `jira_upload.env` 时跳过上传，仅写评论。
|
||
2. **写评论**：若有影响分析内容，调用 `jira_add_comment` 将影响分析报告正文作为评论写入 issue。
|
||
3. 记录该任务的 issue key。
|
||
|
||
**如果用户选择 0 或搜索无结果：**
|
||
|
||
- 调用 `jira_create_issue` 创建新任务，详情见 `references/workflow.md`
|
||
- 设置 project key: `G3SF`, issue type: `Task`
|
||
- **Summary**：必须在标题前添加 `[G3SF]` 前缀，格式为 `[G3SF] 提炼后的改动摘要`
|
||
- **Description**：完整影响分析报告（Markdown 格式）；若本任务需开发计划/任务摘要，可在创建后通过附件上传
|
||
- **Assignee**：必须设置为当前登录账号（由 MCP 传入当前用户或等效参数）
|
||
- 获取返回的新 issue key（如 `G3SF-123`）
|
||
- 若已配置 `jira_upload.env` 且本任务需要文档，创建成功后按公司命名写入并上传对应 MD 文件到该新 Issue
|
||
|
||
### Step 5 - 更新 Git 提交信息
|
||
|
||
使用获取到的 Jira 编号，通过 `git commit --amend` 更新 commit message。**严禁 push**。
|
||
|
||
**注意**：在 Windows PowerShell 环境下，需确保 UTF8 编码以防止中文乱码。
|
||
|
||
```powershell
|
||
# 设置 UTF8 编码
|
||
$OutputEncoding = [System.Text.Encoding]::UTF8
|
||
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
|
||
|
||
$origMsg = (git log -1 --format="%B").TrimEnd()
|
||
$jiraKey = "G3SF-123" # 实际获取到的 key
|
||
|
||
# 使用 --cleanup=verbatim 确保原始消息格式不被 git 自动修剪导致编码转换问题
|
||
git commit --amend -m "$origMsg`n`n**** Jira $jiraKey" --cleanup=verbatim
|
||
```
|
||
|
||
完成后告知用户：
|
||
|
||
```
|
||
绑定成功：
|
||
Jira: G3SF-123 (https://your-jira/browse/G3SF-123)
|
||
Commit: <git log --oneline -1 的结果>
|
||
```
|
||
|
||
---
|
||
|
||
## 相关参考
|
||
|
||
- **公司 Jira 附件文档政策**（何时附加哪些文件）：`references/jira_commit_docs_policy.md`
|
||
- **报告模板、三文档说明与错误处理**：`references/workflow.md`
|
||
- **上传附件配置**：`references/env_config.md`；脚本 `scripts/upload_attachment.py`，依赖见 `scripts/requirements.txt`
|