agent-skills/skills/g3fo-commit-jira/SKILL.md

---
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`