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

name, description

name	description
g3fo-commit-jira	G3FO 项目 Git 提交规范自动化工具。**AI 必须严格按 Step 1→5 线性执行**（见 SKILL 内「AI 执行契约」），每步完成后再进入下一步；强制 git 修订号校验与 HEAD 校验（amend 场景）；Jira 附件仅用 upload_attachment.py。按任务类型生成文档并上传，评论影响分析，最后 amend 追加 Jira、禁止 push。详见 references/agent_execution_checklist.md。

G3FO Commit Jira 技能

本技能通过 git 修订号自动分析改动，绑定/创建 Jira 任务，按公司 Jira 工单附件文档政策生成并上传所需文档（开发计划、影响分析、任务摘要），并更新 commit message。

公司文档政策（自 2026-03-09 起）：何时附加哪些文件见 references/jira_commit_docs_policy.md。
报告模板、任务类型判定与 JQL 参考 references/workflow.md。

---

AI 执行契约（防走偏，必读且优先于即兴发挥）

1. 线性流程，禁止跳步

必须按 Step 1 → Step 2 → Step 3 → Step 4 → Step 5 顺序执行。每完成一步，在回复中用一句话标明 Step N 已完成，再进入下一步。禁止在未完成前置步骤时执行后续操作。

在未完成…	禁止执行…
Step 1：git rev-parse <hash> 成功；若需 amend，已确认该 hash 就是当前 HEAD	调用 Jira、生成报告正文、落盘 <KEY>_*.md、git commit --amend
Step 2：已对照政策表写出任务类型 + 三文档各是否需要（✅/❌）	批量生成无关文档，或该写报告却跳过
Step 3：已持有真实 Jira Issue Key（用户给出 / 用户从列表选定 / 新建命令返回的 key）	以真实路径上传附件、写绑定该 Issue 的评论（禁止用 JIRA-XXX 等占位 Key 落盘上传）
Step 4：本任务在 Jira 侧应做的上传/评论/建单已按政策做完	git commit --amend

2. 红线（违反即视为流程错误）

1. 禁止 git push。本技能只做到 amend 为止。
2. 禁止跳过 git rev-parse <hash>；amend 场景下禁止在 hash ≠ HEAD 时仍执行 amend。
3. 禁止 amend 已推送的提交（除非用户明确要求并确认风险）。使用 git branch -r --contains <hash> 检测。
4. 禁止用 Atlassian MCP 或其它方式冒充「已上传 MD 附件」；上传文件 必须 使用 scripts/upload_attachment.py（MCP 无可靠上传能力时不得虚构成功）。
5. 禁止在用户未选定 Issue、也未完成新建并取得 Key 的情况下，把某 Key 写进 commit message。
6. 禁止未读 references/jira_commit_docs_policy.md（或本 SKILL 中的条件表）就默认「三份全要」或「一律不要文档」。
7. 禁止在用户已提供 Jira 编号时仍执行搜索、展示列表或创建新 Issue。

3. Step 3 交互规则（易走偏）

• 用户已给 Jira 编号 → 直接进入 Step 4，Key = 用户给的编号，禁止执行搜索、展示列表或创建新 Issue。
• 用户未给 → 搜索展示列表后，必须等待用户输入 1～N 或 0（或明确同意新建），禁止擅自替用户选一个 Issue 绑定。
• 搜索为空 → 可进入新建流程；新建成功后 Key 以 API 返回为准。

4. 自检

逐步执行时可对照 references/agent_execution_checklist.md 逐项确认。

---

前置要求

1. 强制提供 Git 修订号 (hash)

用户必须提供一个有效的 git 修订号（如 HEAD 或具体的 hash）。

• 校验逻辑：使用 git rev-parse <hash> 检查修订号是否存在。
• 错误处理：如果修订号无效或找不到，必须 停止操作并提示用户："找不到修订号 <hash>，请提供正确的 git 修订号（例如 HEAD 或 7 位以上的 commit hash）。"
• 路径要求：必须在相关的项目根目录下执行 git 命令。如果当前目录不是 git 仓库或不是目标项目，请提示用户切换到正确的项目路径。
• 已 push 提交检测：使用 git branch -r --contains <hash> 检查提交是否已推送到远程。如果已推送，默认跳过 Step 5（amend），仅完成 Jira 绑定和文档上传，并告知用户：

  "提交 <hash> 已推送到远程，无法 amend。已完成 Jira 绑定和文档上传。如需修改 commit message，请手动处理或提供特别说明。"

• 例外：如果用户明确要求修改已 push 的提交（如通过 --force 或其他方式），需用户确认风险后再执行。

2. Jira 编号 (可选)

用户可以主动提供 Jira 编号（如 G3SF-123）。

• 如果提供了 Jira 编号，直接使用该编号，跳过「查找/选择/新建 Jira 任务」的步骤，进入 Step 4 上传文档和评论。
• 如果未提供，则按流程自动查找或提示用户新建。

3. Jira 访问方式（二选一）

方式	适用场景
REST 脚本（推荐通用）	任意 IDE；仅需 jira_upload.env（与上传附件同一套 Token）。查 Issue、新建 Task、写评论、上传附件全部可走脚本。
Atlassian MCP	仅 Cursor 等已安装并授权 Atlassian 插件的环境；可与脚本混用（附件仍必须用脚本）。

无 MCP 时：必须配置 jira_upload.env，并用 scripts/jira_cli.py 完成 Step 3/4 中的查询、创建与评论（见下文「无 MCP 执行要点」）。

有 MCP 时：可用 MCP 搜索/创建/评论；或仍用 jira_cli.py（行为一致，便于脚本化）。

4. jira_upload.env（上传附件 + 无 MCP 时全部 Jira API）

• 在技能目录 skills/g3fo-commit-jira/ 放置 jira_upload.env（或 --config 指定），包含：JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_TOKEN。示例见 jira_upload.env.example，说明见 references/env_config.md。
• 上传附件：scripts/upload_attachment.py（MCP 不支持上传文件）。
• 无 MCP 时查 Jira / 建单 / 评论：scripts/jira_cli.py，与上传使用相同 Token，详见 references/env_config.md 与 references/workflow.md「无 MCP / jira_cli」。
• 若未配置：无法调用 Jira API；须提示用户创建 jira_upload.env 或在本机 Cursor 使用 MCP。

---

执行步骤（严格顺序）

提醒：仅当上一节「执行契约」中本步的前置条件已满足时，才执行本节对应步骤。

Step 1 - 获取提交内容

git show <hash>                     # 获取 diff + 元数据
git log -1 --format="%B" <hash>     # 获取原始 commit message
git branch -r --contains <hash>     # 检查是否已推送到远程（有输出则已 push）

分析要点：

• 涉及的服务模块/包名
• 新增/修改/删除的方法与接口
• 逻辑改动的核心目的
• 是否已推送：如果 git branch -r --contains <hash> 有输出，说明已推送，Step 5 将跳过 amend

Step 2 - 判定任务类型并确定需生成的文档

前置：Step 1 已完成。
根据改动内容与 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 命名保存并上传。

文档保存路径规则：

• 所有生成的 MD 文档统一保存到项目根目录下的 doc/{日期} 文件夹
• 日期格式为 YYYY-MM-DD（如 doc/2026-03-26）
• 若该文件夹不存在，必须先创建再保存文件
• 示例路径：doc/2026-03-26/G3SF-123_Impact_Analysis.md

Step 3 - 确定 Jira 任务

前置：Step 2 已完成（至少已判定文档需求；若需文档，可先草稿内容，真实 Key 确定后再按 <KEY>_*.md 保存）。

1. 如果用户已提供 Jira 编号：

• 直接使用该编号（如 G3SF-123），跳过查找、选择和新建流程，直接进入 Step 4。
• 不执行 JQL 搜索，不展示列表，不创建新 Issue。

2. 如果用户未提供 Jira 编号：

• 使用 JQL 查找当前用户在 G3SF 项目下的进行中任务（limit 5）：

project = G3SF AND assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC

• 有 MCP：用 MCP 的 JQL 搜索，展示列表。
• 无 MCP：执行（PowerShell 用 ; 分隔）：

  python skills/g3fo-commit-jira/scripts/jira_cli.py --config "skills/g3fo-commit-jira/jira_upload.env" search --limit 5
  

  可加 --format json 供解析。展示列表供用户选择，或输入 0 新建。
• 如果搜索结果为空，自动进入新建流程。

Step 4 - 写入 Jira（附件 + 评论）

前置：已持有本任务最终 Issue Key（Step 3）。

附件命名规范（公司要求）：上传到 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 生成的各文档内容，按公司规范命名写入项目 doc/{日期} 目录（日期格式 YYYY-MM-DD，若不存在则先创建），再调用上传脚本。PowerShell 中不要用 &&，改用 ; 或换行。

   # 创建日期目录（若不存在）
   $dateFolder = "doc/$(Get-Date -Format 'yyyy-MM-dd')"
   if (-not (Test-Path $dateFolder)) { New-Item -ItemType Directory -Path $dateFolder -Force }
   
   # 示例：需要三份文档时，先写入 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 "$dateFolder/G3SF-123_Impact_Analysis.md" --file "$dateFolder/G3SF-123_Dev_Plan.md" --file "$dateFolder/G3SF-123_Task_Summary.md"
   

   若本任务仅需影响分析，则只写入并上传 G3SF-123_Impact_Analysis.md。未配置 jira_upload.env 时跳过上传；有 MCP 时可仅写评论，无 MCP 则必须配置 env 才能完成评论。

2. 写评论（有影响分析正文时）：

   • MCP：jira_add_comment，正文为影响分析报告（插件侧多为 Markdown 渲染）。
   • 无 MCP：jira_cli.py comment/create 会将常见 Markdown（#～###### 标题、-/1. 列表、**粗体**、`代码`、代码块、[链](url) 等）转为 Jira ADF，在网页上与富文本一致；仍建议长文用 --body-file。将报告写入临时文件后：

     python skills/g3fo-commit-jira/scripts/jira_cli.py --config "skills/g3fo-commit-jira/jira_upload.env" comment --issue "G3SF-123" --body-file "path\to\impact_body.md"
     

     或使用 --body "..."（长文建议 --body-file）。

3. 记录该任务的 issue key。

如果用户选择 0 或搜索无结果：

• MCP：调用 jira_create_issue（见 references/workflow.md）。
• 无 MCP：使用 jira_cli.py create（经办人默认为 Token 对应用户）：

  python skills/g3fo-commit-jira/scripts/jira_cli.py --config "skills/g3fo-commit-jira/jira_upload.env" create --summary "[G3SF] 提炼后的改动摘要" --description-file "path\to\impact.md"
  

  脚本会打印新 issue key（如 G3SF-123）；可加 --format json 解析 key 字段。

新建 Issue 字段约定（两种途径均需遵守）：

• project: G3SF，issuetype: Task

• Summary：[G3SF] 前缀 + 一句话摘要

• Description：完整影响分析（Markdown 可先写入文件再用 --description-file）

• Assignee：当前用户（MCP 传 accountId；jira_cli 默认 assignee = API Token 对应账号）

• 若需要文档，创建成功后按公司命名上传对应 MD 到该 Issue

Step 5 - 更新 Git 提交信息

前置：Step 4 已按政策完成（无需文档的绑定类任务可跳过上传/评论，但须已有 Key）。

检查提交是否已推送：

git branch -r --contains <hash>

• 如果有输出，说明提交已推送到远程分支，跳过 amend，告知用户：

  "提交 <hash> 已推送到远程，无法 amend。已完成 Jira 绑定和文档上传。如需修改 commit message，请手动处理或提供特别说明。"

• 如果无输出，说明提交未推送，继续执行 amend。

执行 amend（仅当未推送时）：

使用获取到的 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 编号到 commit message

已推送时：

绑定完成（提交已推送，未修改 commit message）：
   Jira: G3SF-123  (https://your-jira/browse/G3SF-123)
   Commit: <git log --oneline -1 的结果>
   提示：提交已推送到远程，如需修改 commit message 请手动处理

---

相关参考

• AI 逐步检查清单（防走偏）：references/agent_execution_checklist.md
• 公司 Jira 附件文档政策（何时附加哪些文件）：references/jira_commit_docs_policy.md
• 报告模板、三文档说明与错误处理：references/workflow.md
• 上传附件配置：references/env_config.md；脚本 scripts/upload_attachment.py，依赖见 scripts/requirements.txt