ken.li
44b13c96f6
- 添加已推送提交检查，避免不安全的 amend 操作
- 规范文档保存路径为 `doc/{日期}` 格式
- 扩展 markdown 解析支持表格和更多格式
- 优化 Jira 搜索 API 调用方式
267 lines
15 KiB
Markdown
267 lines
15 KiB
Markdown
---
|
||
name: g3fo-commit-jira
|
||
description: 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 - 获取提交内容
|
||
|
||
```powershell
|
||
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 用 `;` 分隔）：
|
||
```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 中不要用 `&&`，改用 `;` 或换行。
|
||
|
||
```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`。将报告写入临时文件后：
|
||
```powershell
|
||
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 对应用户）：
|
||
```powershell
|
||
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）。
|
||
|
||
**检查提交是否已推送**：
|
||
```powershell
|
||
git branch -r --contains <hash>
|
||
```
|
||
- 如果有输出，说明提交已推送到远程分支，**跳过 amend**，告知用户：
|
||
> "提交 `<hash>` 已推送到远程，无法 amend。已完成 Jira 绑定和文档上传。如需修改 commit message，请手动处理或提供特别说明。"
|
||
- 如果无输出，说明提交未推送，继续执行 amend。
|
||
|
||
**执行 amend（仅当未推送时）**：
|
||
|
||
使用获取到的 Jira 编号，通过 `git commit --amend` 更新 commit message。**严禁 push**。
|
||
|
||
**注意**：在 Windows PowerShell 环境下，需确保 UTF8 编码以防止中文乱码。
|
||
|
||
```powershell
|
||
# 设置 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`
|