agent-skills/skills/g3fo-commit-jira/references/workflow.md

G3FO Commit Jira — 详细工作流参考

目录

0. AI 执行顺序提醒
1. 公司 Jira 附件文档政策
2. Step 1: 获取并解析提交内容
3. Step 2: 任务类型判定与三文档模板
4. Step 3: Jira 任务查找与确认
5. Step 4: Jira 字段映射与写入
6. Step 5: Git Amend 命令详解
7. 错误处理表
8. Atlassian MCP 工具速查

---

AI 执行顺序提醒

与 SKILL.md 中「AI 执行契约」 一致：必须 Step 1 → 2 → 3 → 4 → 5，不可跳步。附件仅通过 upload_attachment.py；禁止 push。
逐步打勾请用 references/agent_execution_checklist.md。

---

公司 Jira 附件文档政策

自 2026年3月9日 起，何时附加「开发计划」「影响分析」「任务摘要」以公司强制性指南为准。
完整政策与详细条件表见 references/jira_commit_docs_policy.md。

• 附件命名规范：上传到 Jira 的 MD 必须命名为
  <JIRA-ID>_Dev_Plan.md、<JIRA-ID>_Impact_Analysis.md、<JIRA-ID>_Task_Summary.md
  例如：G3SF-123_Impact_Analysis.md。
• 根据任务类型仅生成并上传“需要”的文档；无需文档的琐碎改动仍可绑定 Jira 并 amend，但不生成报告、不写评论、不上传附件。

---

Step 1: 获取并解析提交内容

命令

# 检查 hash 是否为 HEAD
$head = git rev-parse HEAD
$provided = git rev-parse <hash>
if ($head -ne $provided) { Write-Error "提交不是 HEAD，无法 amend" }

# 检查提交是否已推送到远程
git branch -r --contains <hash>
# 如果有输出，说明已推送，Step 5 将跳过 amend

# 获取完整 diff 和元数据
git show <hash>

# 仅获取原始 commit message（用于后续 amend 保留）
git log -1 --format="%B" <hash>

# 列出修改的文件（不含 diff 内容，快速预览）
git diff-tree --no-commit-id -r --name-status <hash>

解析要点

从 git show 输出中提取：

信息	说明
--- a/path / +++ b/path	修改的文件路径
@@ ... @@ 上下文	修改的类名、方法名
+ 行	新增代码（方法签名、接口、配置）
- 行	删除/替换代码
文件路径中的包名	推断所属服务（g3fo-trade-service, g3fo-margin-service 等）
git branch -r --contains 输出	是否已推送（有输出 = 已推送，跳过 amend）

G3FO 服务包路径规律：

• com.afe.g3fo.<service-short-name>.* → 对应服务
• controller / api → REST 接口层
• facade / facade.impl → Dubbo 接口层
• service / service.impl → 业务逻辑层

---

Step 2: 任务类型判定与三文档模板

2.1 按任务类型确定需生成的文档

任务类型	开发计划	影响分析	任务摘要
漏洞修复——简单（如拼写、界面对齐）	❌	❌	❌
漏洞修复——中等（范围有限的逻辑错误）	❌	✅	❌
漏洞修复——复杂/高风险（并发、核心模块）	✅	✅	✅
小幅度增强（如小效用方法）	❌	✅	❌
新功能/模块	✅	✅	✅
主要重构	✅	✅	✅
配置/基础设施变更	❌	✅	❌

生成内容后，在取得 Jira 编号后按公司规范保存为 <JIRA-ID>_Dev_Plan.md / _Impact_Analysis.md / _Task_Summary.md 再上传。无需文档时跳过生成与上传，仅绑定 Jira 并 amend。

2.2 影响分析报告模板

生成影响分析时严格按以下结构输出（Markdown 格式）：

## 影响分析报告

### 1. 改动概览
- **背景与目标**：[说明为什么改、解决什么问题]
- **涉及模块**：[列举受影响的服务/模块，如 g3fo-trade-service、g3fo-margin-service]
- **改动类型**：功能新增 / 缺陷修复 / 重构 / 配置变更（选一或多个）

### 2. 方法级改动分析

| 文件/类 | 方法/接口 | 改动说明 | 行为是否变更 |
|---------|----------|---------|------------|
| XxxService.java | `calculateMargin()` | 新增空值校验 | 否（边界补强） |

### 3. 调用方与影响范围

| 调用方 | 文件路径 | 影响说明 |
|--------|---------|---------|
| XxxController | controller/XxxController.java | 入参校验增强，现有调用方兼容 |

- **破坏性变更**：是 / 否
- 如为"是"，具体变更点：[列出方法签名、返回值、异常类型变化]

### 4. 风险与回滚
- **风险级别**：低 / 中 / 高
- **风险说明**：[说明原因]
- **回滚方式**：回退版本 / 关闭特性开关 / 回滚配置
- **回滚方式是否简单**：是 / 否

### 5. 验证与测试
- **已执行测试**：单测 / 集成测试 / 冒烟测试（选已执行的）
- **关键用例**：[简述关键场景及预期结果]
- **需线上观察**：[列出需关注的日志关键字、监控指标或告警项]

如果 diff 信息不足以确认调用方，在报告中注明：「建议在代码库中搜索 <方法名> 确认所有调用方」。

2.3 开发计划模板（仅当任务类型要求时生成）

开发计划用于概述步骤、设计方法和技术决策。结构示例：

## 开发计划

### 1. 目标与范围
- **目标**：[本任务要达成的结果]
- **范围**：[涉及模块、接口、配置等]

### 2. 步骤与设计方法
1. [步骤一：如需求分析、接口设计]
2. [步骤二：如实现方案、关键类/方法]
3. [步骤三：如测试与验证]

### 3. 技术决策
- [关键技术选型或实现方式及理由]
- [与现有架构的衔接方式]

2.4 任务摘要模板（仅当任务类型要求时生成）

任务摘要用于简要回顾所完成的工作，包括任何偏离计划的地方。结构示例：

## 任务摘要

### 1. 完成内容
- [已完成的主要改动与交付物]

### 2. 与计划差异（如有）
- [若实际实现与开发计划有偏差，在此说明原因与结果]

### 3. 后续建议（可选）
- [遗留事项、后续优化或文档更新建议]

---

Step 3: Jira 任务查找与确认

用户已提供 Jira 编号

如果用户已提供 Jira 编号（如 G3SF-123）：

• 直接使用该编号，跳过 JQL 搜索、列表展示和新建流程
• 禁止执行搜索、展示列表或创建新 Issue
• 直接进入 Step 4 上传文档和评论

用户未提供 Jira 编号

执行 JQL 查询：

JQL 查询

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

• 限制返回 5 条，避免信息过载
• 若返回 0 条，直接告知用户并自动进入新建流程

展示格式

找到以下 G3SF 进行中任务，请输入编号绑定，或输入 0 新建：

1. G3SF-101  [修复保证金计算逻辑]  状态: In Progress
2. G3SF-98   [交易服务批量撤单性能优化]  状态: To Do
3. G3SF-95   [用户服务登录接口重构]  状态: In Progress

0. 新建一个 G3SF Task

请输入 (1/2/3/0)：

确认规则

用户输入	行为
1~N	使用对应任务，写入评论
0	新建 Jira Task
n / no	等同于 0，新建任务
其他	重新提问一次

---

Step 4: Jira 字段映射与写入

新建 Issue 字段

调用 jira_create_issue（或鉴权后发现的等效工具），传入：

字段	值
project	G3SF
issuetype	Task
summary	必须带 [G3SF] 前缀，格式：[G3SF] 提炼后的一句话描述（≤100 字符）
description	完整影响分析报告（Markdown / ADF 格式）
assignee	必须为当前登录账号（传入当前用户 accountId/name，确保新建任务经办人为自己）

Summary 生成规则：

• 标题必须统一加前缀：[G3SF] + 正文。例如：[G3SF] [g3fo-trade-service] 修复批量撤单时的并发锁问题
• 正文优先使用原始 commit message 的第一行（若描述清晰），否则根据修改内容生成：[服务名] 功能描述

新建 Issue 成功后，若已配置 jira_upload.env 且本任务需要文档，按公司命名将对应 MD 写入本地后上传到该新 Issue。

保存报告为 MD 并上传附件

1. 按公司规范命名并保存：取得 Jira 编号（如 G3SF-123）后，将 Step 2 生成的各文档内容分别写入本地文件，文件名必须为：

   • <JIRA-ID>_Dev_Plan.md
   • <JIRA-ID>_Impact_Analysis.md
   • <JIRA-ID>_Task_Summary.md
     仅保存本任务类型要求的那几份（见 2.1 按任务类型确定需生成的文档）。

   保存路径规则：

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

2. 上传到 Jira 附件：Atlassian MCP 不支持上传文件，使用本技能自带脚本上传上述 MD 到当前 Issue：

   • 配置文件：在技能目录下配置 jira_upload.env（JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_TOKEN），详见 references/env_config.md。
   • 命令示例（PowerShell 用 ; 连接，勿用 &&），按需上传多文件：

     # 创建日期目录（若不存在）
     $dateFolder = "doc/$(Get-Date -Format 'yyyy-MM-dd')"
     if (-not (Test-Path $dateFolder)) { New-Item -ItemType Directory -Path $dateFolder -Force }
     
     python skills/g3fo-commit-jira/scripts/upload_attachment.py --config "skills/g3fo-commit-jira/jira_upload.env" --issue "G3SF-101" --file "$dateFolder/G3SF-101_Impact_Analysis.md" --file "$dateFolder/G3SF-101_Dev_Plan.md" --file "$dateFolder/G3SF-101_Task_Summary.md"
     

   • 未配置 jira_upload.env 时跳过上传，仅写评论。

写入已有 Issue（评论）

调用 jira_add_comment（或等效工具），字段：

字段	值
issue_key	用户选择的 issue key，如 G3SF-101
body	完整影响分析报告（与已保存的 MD 内容一致）

Jira 描述格式兼容

部分 Jira 实例使用 Atlassian Document Format (ADF) 而非纯 Markdown。若 MCP 工具提示格式错误，则：

• 将 Markdown 内容作为纯文本写入
• 或使用 {code} 块包裹（Jira Wiki 格式兼容）

---

Step 5: Git Amend 命令详解

检查提交是否已推送

在执行 amend 前，必须检查提交是否已推送到远程：

# 检查提交是否已推送
$pushedBranches = git branch -r --contains <hash>
if ($pushedBranches) {
    Write-Host "提交已推送到远程，跳过 amend"
    Write-Host "已完成 Jira 绑定和文档上传"
    Write-Host "如需修改 commit message，请手动处理或提供特别说明"
    # 跳过 amend，直接结束
    return
}

已推送的处理：

• 如果 git branch -r --contains <hash> 有输出，说明提交已推送到远程分支
• 跳过 amend，仅完成 Jira 绑定和文档上传
• 告知用户提交已推送，无法 amend
• 例外：用户明确要求修改已推送的提交时，需确认风险后再执行

PowerShell（Windows 环境）

在 Windows PowerShell 中，直接使用 $origMsg 可能会导致编码问题（乱码）。必须显式指定输出编码为 UTF8。

# 设置控制台和输出编码为 UTF8，防止中文乱码
$OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# 获取原始 commit message（保留完整内容）
$origMsg = (git log -1 --format="%B").TrimEnd()

# Jira key（从上一步获取）
$jiraKey = "G3SF-123"

# 追加 Jira 行并 amend（不 push）
# 使用 --cleanup=verbatim 确保消息内容不被 git 自动修剪导致编码转换问题
git commit --amend -m "$origMsg`n`n**** Jira $jiraKey" --cleanup=verbatim

Bash/Linux（供参考）

origMsg=$(git log -1 --format="%B" | sed 's/[[:space:]]*$//')
jiraKey="G3SF-123"
git commit --amend -m "$origMsg

**** Jira $jiraKey"

Amend 注意事项

• --amend 只修改 HEAD，不改变工作区内容
• 如果有 GPG 签名要求，告知用户需确认签名
• amend 后 commit hash 会变更，这是正常现象
• 禁止 push：本 skill 不执行 git push，提交操作到 amend 为止

结果验证

git log -1 --format="%B"   # 确认 Jira 行已追加
git log --oneline -1        # 查看 commit 摘要

---

无 MCP：jira_cli.py 速查

与 upload_attachment.py 共用 jira_upload.env（JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_TOKEN）。从仓库根执行时建议 --config 指向技能目录下的配置文件。

操作	命令示例
当前用户（accountId）	python .../jira_cli.py --config ".../jira_upload.env" myself
默认 JQL 搜索（G3SF 进行中、指派给我）	python .../jira_cli.py --config "..." search --limit 5
自定义 JQL	python .../jira_cli.py --config "..." search --jql "project = G3SF AND key = G3SF-1" --limit 10
机器可读	上述命令加 --format json
单条 Issue	python .../jira_cli.py --config "..." issue G3SF-123
新建 Task	python .../jira_cli.py --config "..." create --summary "[G3SF] 标题" --description-file report.md
新建（内联描述）	create --summary "..." --description "多段用\n\n分隔"
添加评论	python .../jira_cli.py --config "..." comment --issue G3SF-123 --body-file impact.md
不上传经办人	create ... --no-assign-self（若站点禁止创建时指定经办人）

说明：create 默认 project=G3SF、issuetype=Task；描述与评论由脚本将 Markdown 转为 Jira Cloud ADF（# 标题、列表、**粗体**、代码块等会按富文本展示，不再出现 ### 原文）。上传 MD 附件仍用 upload_attachment.py。

---

错误处理表

错误场景	检测方式	处理方式
修订号不存在	git rev-parse <hash> 报错	停止，提示用户提供正确的修订号。
提交 hash 不是 HEAD	git rev-parse HEAD ≠ git rev-parse <hash>	停止，提示用户确认 hash（只有 HEAD 才能 amend）。
提交已推送到远程	git branch -r --contains <hash> 有输出	跳过 amend，仅完成 Jira 绑定和文档上传，告知用户提交已推送。
项目路径不正确	git rev-parse --is-inside-work-tree 失败	提示用户在正确的 git 项目目录下操作。
无 MCP 且未配置 jira_upload.env	无法执行 jira_cli / 上传	必须配置 jira_upload.env 或改用 Cursor + MCP。
Atlassian MCP 未鉴权	STATUS.md 有提示 / 工具调用返回 401	调用 mcp_auth，或改用 jira_cli.py。
Atlassian 插件未安装	tools/ 目录为空或 MCP 调用失败	使用 jira_cli.py + jira_upload.env，或在 Cursor 安装 Atlassian 插件
Jira 项目 G3SF 不存在	创建/搜索返回 404/400	提示用户确认 JIRA_BASE_URL、项目 key；create 可用 --project
工作区有未提交变更	git status --porcelain 有输出	警告：amend 会将未暂存变更排除在外，建议先 git add 或 stash
commit message 中已有 Jira 行	message 中包含 **** Jira	跳过追加，提示用户该提交已绑定
用户已提供 Jira 编号	用户输入包含 Jira key	跳过搜索和新建，直接使用用户提供的编号
Jira 搜索无结果	工具返回空列表	直接进入新建流程，无需用户确认
未配置 jira_upload.env	上传前检查配置不存在	有 MCP：跳过上传，仅评论。无 MCP：无法完成 Jira 操作，须配置 env 或使用 MCP。
任务类型判定为「无需文档」	按政策表属简单漏洞/琐碎改动	不生成报告、不写评论、不上传附件；仍执行 Jira 绑定与 commit --amend，将 Jira 编号追加到 commit message

---

Atlassian MCP 工具速查

鉴权成功后，通过列举 mcps/plugin-atlassian-atlassian/tools/ 确认可用工具。常见工具名：

功能	可能的工具名
搜索 Issue	jira_search_issues, jira_jql_search
创建 Issue	jira_create_issue
获取 Issue 详情	jira_get_issue
添加评论	jira_add_comment
更新 Issue	jira_update_issue
获取当前用户	jira_get_current_user
获取项目列表	jira_get_projects
上传附件	MCP 不支持，使用 scripts/upload_attachment.py + jira_upload.env

实际工具名以 tools/ 目录下的 JSON 文件名为准，鉴权后务必先列目录确认。上传附件需使用本技能自带的 Python 脚本，见 references/env_config.md。