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 格式以获得更好的渲染效果
2026-03-23 13:38:41 +08:00
parent cd6c8a0450
commit 57fca4e468
9 changed files with 1018 additions and 78 deletions
@@ -0,0 +1,108 @@
+# 影响分析报告 — g3fo-commit-jira 无 MCP 支持
+
+## 1. 改动概览
+
+- **背景**：技能原依赖 Cursor Atlassian MCP 完成 Jira 搜索/创建/评论；其它 IDE 无 MCP 时无法完成流程。
+- **目标**：在仅配置 `jira_upload.env`（与上传附件相同 Token）时，通过脚本完成查询、创建 Issue、添加评论。
+- **涉及模块**：`skills/g3fo-commit-jira/scripts/`、`SKILL.md`、`references/workflow.md`、`references/env_config.md`。
+- **改动类型**：功能新增（脚本）+ 文档更新。
+
+## 2. 方法级改动分析
+
+| 项 | 说明 |
+|----|------|
+| 新增 `jira_env.py` | 统一加载 `jira_upload.env`，支持在技能根目录查找配置文件。 |
+| 新增 `jira_cli.py` | `myself` / `search` / `issue` / `create` / `comment` REST 调用。 |
+| 修改 `upload_attachment.py` | 改为引用 `jira_env`，行为与原先一致（多一层技能目录 config 查找）。 |
+| SKILL / workflow / env_config | 描述无 MCP 路径与命令示例。 |
+
+**与原有逻辑差异**：上传附件 URL、认证方式未变；配置查找增加 `skills/g3fo-commit-jira/jira_upload.env`。
+
+## 3. 调用方与影响范围
+
+- **调用方**：Agent 按 SKILL 执行；用户手动运行脚本。
+- **破坏性变更**：否。未配置 env 时 `upload_attachment` 仍报错；原 MCP 流程仍可用。
+- **边界**：Jira Server/Data Center 与 Cloud API 差异未专门适配（与现有上传脚本一致，面向 Cloud）。
+
+## 4. 风险与回滚
+
+- **风险级别**：低。新脚本失败时退回 MCP 或仅本地 amend。
+- **回滚**：删除 `jira_cli.py`/`jira_env.py` 并恢复 `upload_attachment.py` 内联配置逻辑；回滚文档。
+- **回滚方式是否简单**：是。
+
+## 5. 验证与测试
+
+- `python -m py_compile` 通过；`jira_cli.py --help` 正常。
+- 真实 Jira 调用需用户环境凭证，未在 CI 中执行。
+
+---
+
+# 影响分析报告 — jira_cli Markdown → ADF 渲染（评论/描述）
+
+## 1. 改动概览
+
+- **背景**：REST 脚本原先把正文整段当作 ADF 段落，`###` 等在 Jira 界面显示为原文，与 Atlassian 插件/MCP 的 Markdown 体验不一致。
+- **目标**：在 `jira_cli.py` 内将常见 Markdown 转为 ADF（heading、list、strong、code、link、codeBlock、rule、blockquote），使 `comment` / `create` 的展示接近网页富文本。
+- **涉及模块**：`scripts/jira_cli.py`、`SKILL.md`。
+- **改动类型**：功能增强（无 API 变更）。
+
+## 2. 方法级改动分析
+
+| 项 | 说明 |
+|----|------|
+| `markdown_to_adf`（新） | 按行解析 Markdown，输出 ADF `doc`。 |
+| `plain_to_adf` | 改为委托 `markdown_to_adf`，保持调用方不变。 |
+| `parse_inline_adf`（新） | 行内 `**`、`` ` ``、`[text](url)`。 |
+
+**与原有逻辑差异**：非 Markdown 行仍按段落（含换行 hardBreak）输出；纯文本行为与旧版「多段段落」接近，但连续单行不再强制 `\\n\\n` 才分段。
+
+## 3. 调用方与影响范围
+
+- **调用方**：`cmd_comment`、`cmd_create` 经 `plain_to_adf` → `markdown_to_adf`。
+- **破坏性变更**：否。极端表格/复杂 MD 语法未实现，可能仍以普通文本行展示。
+- **边界**：与 Jira Cloud ADF 一致；Server/DC 若 API 不同需单独验证。
+
+## 4. 风险与回滚
+
+- **风险级别**：低。若某 ADF 节点被实例拒绝，可回退 `plain_to_adf` 为旧实现。
+- **回滚方式是否简单**：是（恢复旧 `plain_to_adf` 单函数）。
+
+## 5. 验证与测试
+
+- 本地 `markdown_to_adf` 样例 JSON 结构校验；`py_compile` 通过。
+- 完整评论 POST 需对接真实 Jira。
+
+---
+
+# 影响分析报告 — AI 执行流程防走偏（SKILL / workflow / checklist）
+
+## 1. 改动概览
+
+- **背景**：不同 AI 执行本技能时偶发跳步、先写 Jira 再看 diff、占位 Key 上传、误用 MCP 冒充附件等。
+- **目标**：在文档层强制 **Step 1→5 线性顺序**、门禁表、红线与 Step 3 交互规则；新增逐步检查清单供 Agent 对照。
+- **涉及模块**：`SKILL.md`、`references/workflow.md`、新增 `references/agent_execution_checklist.md`。
+- **改动类型**：文档 / 流程约束增强（无脚本行为变更）。
+
+## 2. 方法级改动分析
+
+| 项 | 说明 |
+|----|------|
+| `SKILL.md` | 前置「AI 执行契约」、各 Step「前置」说明、frontmatter description 强调线性流程。 |
+| `workflow.md` | 目录增加「AI 执行顺序提醒」，链回 SKILL 与 checklist。 |
+| `agent_execution_checklist.md`（新） | Step 0～5 打勾表 + 走偏速查。 |
+
+**与原有逻辑差异**：仅约束 Agent 阅读与执行顺序；不改变 Python/API 行为。
+
+## 3. 调用方与影响范围
+
+- **调用方**：所有读取本技能的 Agent。
+- **破坏性变更**：否。用户手动跑脚本不受影响。
+
+## 4. 风险与回滚
+
+- **风险级别**：低。文档过长可能略增 token；可精简 checklist。
+- **回滚方式是否简单**：是（还原 SKILL/workflow、删除 checklist）。
+
+## 5. 验证与测试
+
+- 文档结构与人读一致性自检；无自动化测试。