AFE_SZ_DEV/agent-skills
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(jira): 增强提交检查和文档路径规范

Browse Source 
- 添加已推送提交检查，避免不安全的 amend 操作
- 规范文档保存路径为 `doc/{日期}` 格式
- 扩展 markdown 解析支持表格和更多格式
- 优化 Jira 搜索 API 调用方式
This commit is contained in:
ken.li
2026-04-02 17:38:39 +08:00
parent 062e9a652b
commit 44b13c96f6
5 changed files with 244 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/g3fo-commit-jira/SKILL.md
+50 -11
View File
@@ -29,13 +29,15 @@ description: G3FO 项目 Git 提交规范自动化工具。**AI 必须严格按
1. **禁止 `git push`**。本技能只做到 amend 为止。
2. **禁止跳过** `git rev-parse <hash>`；amend 场景下禁止在 **hash ≠ HEAD** 时仍执行 amend。
3. **禁止用 Atlassian MCP 或其它方式冒充「已上传 MD 附件」**；上传文件 **必须** 使用 `scripts/upload_attachment.py`（MCP 无可靠上传能力时不得虚构成功）。
4. **禁止**在用户未选定 Issue、也未完成新建并取得 Key 的情况下，把某 Key 写进 commit message。
5. **禁止**未读 `references/jira_commit_docs_policy.md`（或本 SKILL 中的条件表）就默认「三份全要」或「一律不要文档」。
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 = 用户给的编号。
- 用户**已给** Jira 编号 → **直接进入 Step 4**，Key = 用户给的编号，**禁止执行搜索、展示列表或创建新 Issue**。
- 用户**未给** → 搜索展示列表后，**必须等待用户输入 1～N 或 0**（或明确同意新建），**禁止**擅自替用户选一个 Issue 绑定。
- 搜索为空 → 可进入新建流程；新建成功后 Key 以 API 返回为准。
@@ -51,13 +53,16 @@ description: G3FO 项目 Git 提交规范自动化工具。**AI 必须严格按
用户必须提供一个有效的 git 修订号（如 `HEAD` 或具体的 `hash`）。
- **校验逻辑**：使用 `git rev-parse <hash>` 检查修订号是否存在。
- **错误处理**：如果修订号无效或找不到，**必须** 停止操作并提示用户：“找不到修订号 `<hash>`，请提供正确的 git 修订号（例如 HEAD 或 7 位以上的 commit 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 任务”的步骤。
- 如果提供了 Jira 编号，**直接使用该编号，跳过「查找/选择/新建 Jira 任务」的步骤**，进入 Step 4 上传文档和评论。
- 如果未提供，则按流程自动查找或提示用户新建。
**3. Jira 访问方式（二选一）**
@@ -89,12 +94,14 @@ description: G3FO 项目 Git 提交规范自动化工具。**AI 必须严格按
```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 - 判定任务类型并确定需生成的文档
@@ -116,20 +123,27 @@ git log -1 --format="%B" <hash> # 获取原始 commit message
### Step 2（续）- 生成所需报告内容
对上述判定为“需要”的文档，按 `references/workflow.md` 中的模板生成内容（可先存于内存或临时文件）：
对上述判定为"需要"的文档，按 `references/workflow.md` 中的模板生成内容（可先存于内存或临时文件）：
- **开发计划**：步骤、设计方法、技术决策。
- **影响分析**：改动概览、方法级分析、影响范围、风险与回滚、验证与测试（模板见 workflow.md）。
- **任务摘要**：所完成工作的简要回顾，以及任何偏离计划之处。
生成后先不按“公司附件名”落盘，等取得 Jira 编号后再以 `<JIRA-ID>_*.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。
- **直接使用该编号**（如 `G3SF-123`），**跳过查找、选择和新建流程**，直接进入 Step 4。
- 不执行 JQL 搜索，不展示列表，不创建新 Issue。
**2. 如果用户未提供 Jira 编号：**
- 使用 JQL 查找当前用户在 G3SF 项目下的进行中任务（limit 5）：
@@ -155,11 +169,15 @@ project = G3SF AND assignee = currentUser() AND statusCategory != Done ORDER BY
**如果选择/新建的任务 ID > 0：**
1. **保存并上传附件**（已配置 `jira_upload.env` 且本任务需要文档时）：
将 Step 2 生成的各文档内容，按公司规范命名写入当前项目目录（或 `docs/` 等），再调用上传脚本。PowerShell 中不要用 `&&`，改用 `;` 或换行。
将 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 "G3SF-123_Impact_Analysis.md" --file "G3SF-123_Dev_Plan.md" --file "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 才能完成评论。
@@ -193,6 +211,17 @@ project = G3SF AND assignee = currentUser() AND statusCategory != Done ORDER BY
### 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 编码以防止中文乱码。
@@ -211,10 +240,20 @@ 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 请手动处理
```
---