feat: 添加g3fo-commit-jira skill

2026-03-16 18:11:34 +08:00
parent 2768d58aa3
commit dc2d6697af
13 changed files with 960 additions and 24 deletions
@@ -0,0 +1,333 @@
+# G3FO Commit Jira — 详细工作流参考
+
+## 目录
+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-工具速查)
+
+---
+
+## 公司 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" }
+
+# 获取完整 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` 等） |
+
+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 任务查找与确认
+
+### 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-按任务类型确定需生成的文档)）。保存位置：当前 Git 项目根目录或项目约定目录（如 `docs/`）。
+2. **上传到 Jira 附件**：Atlassian MCP 不支持上传文件，使用本技能自带脚本上传上述 MD 到当前 Issue：
+   - 配置文件：在技能目录下配置 `jira_upload.env`（`JIRA_BASE_URL`、`JIRA_EMAIL`、`JIRA_API_TOKEN`），详见 `references/env_config.md`。
+   - 命令示例（PowerShell 用 `;` 连接，勿用 `&&`），按需上传多文件：
+     ```powershell
+     python skills/g3fo-commit-jira/scripts/upload_attachment.py --config "skills/g3fo-commit-jira/jira_upload.env" --issue "G3SF-101" --file "G3SF-101_Impact_Analysis.md" --file "G3SF-101_Dev_Plan.md" --file "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 命令详解
+
+### 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 摘要
+```
+
+---
+
+## 错误处理表
+
+| 错误场景 | 检测方式 | 处理方式 |
+|---------|---------|---------|
+| 修订号不存在 | `git rev-parse <hash>` 报错 | **停止**，提示用户提供正确的修订号。 |
+| 提交 hash 不是 HEAD | `git rev-parse HEAD` ≠ `git rev-parse <hash>` | 停止，提示用户确认 hash（只有 HEAD 才能 amend）。 |
+| 项目路径不正确 | `git rev-parse --is-inside-work-tree` 失败 | 提示用户在正确的 git 项目目录下操作。 |
+| Atlassian MCP 未鉴权 | `STATUS.md` 有提示 / 工具调用返回 401 | 调用 `mcp_auth`，等待用户完成授权。 |
+| Atlassian 插件未安装 | `tools/` 目录为空或 MCP 调用失败 | 引导用户在 Cursor Settings → MCP 安装 Atlassian 插件 |
+| Jira 项目 G3SF 不存在 | `jira_create_issue` 返回 404/400 | 提示用户确认 Jira 实例 URL 和项目 key |
+| 工作区有未提交变更 | `git status --porcelain` 有输出 | 警告：amend 会将未暂存变更排除在外，建议先 `git add` 或 stash |
+| commit message 中已有 Jira 行 | message 中包含 `**** Jira` | 跳过追加，提示用户该提交已绑定 |
+| Jira 搜索无结果 | 工具返回空列表 | 直接进入新建流程，无需用户确认 |
+| 未配置 jira_upload.env | 上传前检查配置不存在 | 跳过上传附件，仅通过 jira_add_comment 写入报告；提示用户可配置后使用脚本上传 |
+| 任务类型判定为「无需文档」 | 按政策表属简单漏洞/琐碎改动 | 不生成报告、不写评论、不上传附件；仍执行 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`。