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

name, description

name	description
g3fo-commit-jira	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 - 获取提交内容

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 中不要用 &&，改用 ; 或换行。

   # 示例：需要三份文档时，先写入 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 编码以防止中文乱码。

# 设置 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