feat(g3fo-commit-jira): 新增无 MCP 的 Jira CLI 并增强 AI 执行流程约束
- 新增 `jira_cli.py` 脚本，支持在不依赖 Atlassian MCP 的环境下通过同一 Jira Token 进行搜索、创建 Issue 和评论 - 新增共享配置模块 `jira_env.py`，统一加载 `jira_upload.env` 并支持在技能根目录查找配置文件 - 更新 `SKILL.md` 和参考文档，增加「AI 执行契约」和详细的前置条件说明，强制 Step 1→5 线性执行顺序 - 新增 `agent_execution_checklist.md` 检查清单，防止 AI 跳步、误用工具或未等用户确认就绑定 Issue - 改进 `jira_cli.py` 的评论和描述生成，将常见 Markdown 语法转换为 Jira ADF 格式以获得更好的渲染效果
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: g3fo-commit-jira
|
||||
description: G3FO 项目 Git 提交规范自动化工具。强制要求提供 git 修订号（hash），支持用户直接提供 Jira 编号或自动查找/创建 Jira 任务。按任务类型（漏洞修复/新功能/重构等）判定需附加的文档（开发计划、影响分析、任务摘要），生成对应 MD 并按公司规范命名（<JIRA-ID>_Dev_Plan.md / _Impact_Analysis.md / _Task_Summary.md）上传到 Jira 附件，将影响分析写入评论，最后将 Jira 编号追加到 commit message 末尾后提交（不 push）。适用于 G3FO/G3SF 项目的所有 git 提交场景。
|
||||
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 技能
|
||||
@@ -12,6 +12,39 @@ description: G3FO 项目 Git 提交规范自动化工具。强制要求提供 gi
|
||||
|
||||
---
|
||||
|
||||
## 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. **禁止用 Atlassian MCP 或其它方式冒充「已上传 MD 附件」**；上传文件 **必须** 使用 `scripts/upload_attachment.py`（MCP 无可靠上传能力时不得虚构成功）。
|
||||
4. **禁止**在用户未选定 Issue、也未完成新建并取得 Key 的情况下，把某 Key 写进 commit message。
|
||||
5. **禁止**未读 `references/jira_commit_docs_policy.md`（或本 SKILL 中的条件表）就默认「三份全要」或「一律不要文档」。
|
||||
|
||||
### 3. Step 3 交互规则（易走偏）
|
||||
|
||||
- 用户**已给** Jira 编号 → 直接进入 Step 4，Key = 用户给的编号。
|
||||
- 用户**未给** → 搜索展示列表后，**必须等待用户输入 1～N 或 0**（或明确同意新建），**禁止**擅自替用户选一个 Issue 绑定。
|
||||
- 搜索为空 → 可进入新建流程；新建成功后 Key 以 API 返回为准。
|
||||
|
||||
### 4. 自检
|
||||
|
||||
逐步执行时可对照 **`references/agent_execution_checklist.md`** 逐项确认。
|
||||
|
||||
---
|
||||
|
||||
## 前置要求
|
||||
|
||||
**1. 强制提供 Git 修订号 (hash)**
|
||||
@@ -27,25 +60,29 @@ description: G3FO 项目 Git 提交规范自动化工具。强制要求提供 gi
|
||||
- 如果提供了 Jira 编号，直接引用该编号，跳过“查找/选择 Jira 任务”的步骤。
|
||||
- 如果未提供，则按流程自动查找或提示用户新建。
|
||||
|
||||
**3. Atlassian MCP 授权**
|
||||
**3. Jira 访问方式（二选一）**
|
||||
|
||||
- 查看 `mcps/plugin-atlassian-atlassian/STATUS.md` 确认已在 Cursor 中授权 MCP 插件。
|
||||
- 如果未授权，调用 `mcp_auth`，server: `plugin-atlassian-atlassian`，参数 `{}`。
|
||||
- 若 MCP 插件未安装，引导用户按以下步骤操作：
|
||||
1. 打开 Cursor Settings -> MCP
|
||||
2. 添加名为 `Atlassian` 的插件
|
||||
3. 按照提示完成授权并启用 skill
|
||||
- 确保可用工具在 `mcps/plugin-atlassian-atlassian/tools/` 目录下已列出。
|
||||
| 方式 | 适用场景 |
|
||||
|------|----------|
|
||||
| **REST 脚本（推荐通用）** | 任意 IDE；仅需 `jira_upload.env`（与上传附件**同一套** Token）。查 Issue、新建 Task、写评论、上传附件**全部**可走脚本。 |
|
||||
| **Atlassian MCP** | 仅 Cursor 等已安装并授权 Atlassian 插件的环境；可与脚本混用（附件仍必须用脚本）。 |
|
||||
|
||||
**4. 上传附件配置（用于将影响分析报告 MD 上传到 Jira）**
|
||||
**无 MCP 时**：必须配置 `jira_upload.env`，并用 `scripts/jira_cli.py` 完成 Step 3/4 中的查询、创建与评论（见下文「无 MCP 执行要点」）。
|
||||
|
||||
- Atlassian MCP 插件不支持上传文件，本技能使用自带脚本 `scripts/upload_attachment.py` 将报告 MD 上传为 Issue 附件。
|
||||
- 在技能目录或脚本目录放置 `jira_upload.env`（或使用 `--config` 指定路径），包含：`JIRA_BASE_URL`、`JIRA_EMAIL`、`JIRA_API_TOKEN`。格式见 `jira_upload.env.example`，详细说明见 `references/env_config.md`。
|
||||
- 若未配置，上传附件步骤跳过，仅通过 `jira_add_comment` 写入报告；已配置则先上传 MD 再写评论。
|
||||
**有 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 - 获取提交内容
|
||||
|
||||
@@ -61,7 +98,8 @@ git log -1 --format="%B" <hash> # 获取原始 commit message
|
||||
|
||||
### Step 2 - 判定任务类型并确定需生成的文档
|
||||
|
||||
根据改动内容与 `references/jira_commit_docs_policy.md` 中的**详细条件表**，先判定任务类型，再决定需要生成并上传的文档：
|
||||
**前置**：Step 1 已完成。
|
||||
根据改动内容与 `references/jira_commit_docs_policy.md` 中的**详细条件表**，先判定任务类型，再决定需要生成并上传的文档（须在回复中写明类型与三文档要/不要）：
|
||||
|
||||
| 任务类型 | 开发计划 | 影响分析 | 任务摘要 |
|
||||
|----------|:--------:|:--------:|:--------:|
|
||||
@@ -88,6 +126,8 @@ git log -1 --format="%B" <hash> # 获取原始 commit message
|
||||
|
||||
### Step 3 - 确定 Jira 任务
|
||||
|
||||
**前置**：Step 2 已完成（至少已判定文档需求；若需文档，可先草稿内容，**真实 Key 确定后再按 `<KEY>_*.md` 保存**）。
|
||||
|
||||
**1. 如果用户已提供 Jira 编号：**
|
||||
- 直接使用该编号（如 `G3SF-123`），进入 Step 4。
|
||||
|
||||
@@ -96,11 +136,18 @@ git log -1 --format="%B" <hash> # 获取原始 commit message
|
||||
```
|
||||
project = G3SF AND assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC
|
||||
```
|
||||
- 展示列表供用户选择，或允许用户输入 `0` 新建。
|
||||
- **有 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 附件名）。
|
||||
@@ -115,22 +162,37 @@ project = G3SF AND assignee = currentUser() AND statusCategory != Done ORDER BY
|
||||
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"
|
||||
```
|
||||
|
||||
若本任务仅需影响分析，则只写入并上传 `G3SF-123_Impact_Analysis.md`。未配置 `jira_upload.env` 时跳过上传，仅写评论。
|
||||
2. **写评论**：若有影响分析内容，调用 `jira_add_comment` 将影响分析报告正文作为评论写入 issue。
|
||||
若本任务仅需影响分析，则只写入并上传 `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 或搜索无结果：**
|
||||
|
||||
- 调用 `jira_create_issue` 创建新任务，详情见 `references/workflow.md`
|
||||
- 设置 project key: `G3SF`, issue type: `Task`
|
||||
- **Summary**：必须在标题前添加 `[G3SF]` 前缀，格式为 `[G3SF] 提炼后的改动摘要`
|
||||
- **Description**：完整影响分析报告（Markdown 格式）；若本任务需开发计划/任务摘要，可在创建后通过附件上传
|
||||
- **Assignee**：必须设置为当前登录账号（由 MCP 传入当前用户或等效参数）
|
||||
- 获取返回的新 issue key（如 `G3SF-123`）
|
||||
- 若已配置 `jira_upload.env` 且本任务需要文档，创建成功后按公司命名写入并上传对应 MD 文件到该新 Issue
|
||||
- **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）。
|
||||
使用获取到的 Jira 编号，通过 `git commit --amend` 更新 commit message。**严禁 push**。
|
||||
|
||||
**注意**：在 Windows PowerShell 环境下，需确保 UTF8 编码以防止中文乱码。
|
||||
@@ -159,6 +221,7 @@ git commit --amend -m "$origMsg`n`n**** Jira $jiraKey" --cleanup=verbatim
|
||||
|
||||
## 相关参考
|
||||
|
||||
- **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`
|
||||
|
||||
Reference in New Issue
Block a user