# 影响分析报告 — 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. 验证与测试

- 文档结构与人读一致性自检；无自动化测试。