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

# G3FO Commit Jira — 详细工作流参考

## 目录
0. [AI 执行顺序提醒](#ai-执行顺序提醒)
1. [公司 Jira 附件文档政策](#公司-jira-附件文档政策)
2. [Step 1: 获取并解析提交内容](#step-1-获取并解析提交内容)
3. [Step 2: 任务类型判定与三文档模板](#step-2-任务类型判定与三文档模板)
4. [Step 3: Jira 任务查找与确认](#step-3-jira-任务查找与确认)
5. [Step 4: Jira 字段映射与写入](#step-4-jira-字段映射与写入)
6. [Step 5: Git Amend 命令详解](#step-5-git-amend-命令详解)
7. [错误处理表](#错误处理表)
8. [Atlassian MCP 工具速查](#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: 获取并解析提交内容

### 命令

```powershell
# 检查 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 格式）：

```markdown
## 影响分析报告

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

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

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

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

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

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

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

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

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

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

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

```markdown
## 开发计划

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

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

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

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

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

```markdown
## 任务摘要

### 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 按任务类型确定需生成的文档](#21-按任务类型确定需生成的文档)）。
   
   **保存路径规则**：
   - 所有文档统一保存到项目根目录下的 `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 用 `;` 连接，勿用 `&&`），按需上传多文件：
     ```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 前，必须检查提交是否已推送到远程：

```powershell
# 检查提交是否已推送
$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。

```powershell
# 设置控制台和输出编码为 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（供参考）

```bash
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` 为止

### 结果验证

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