agent-skills/skills/g3fo-commit-jira/IMPACT_ANALYSIS.md

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

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