--- name: jira-mcp-setup description: "统一的 Jira 问题处理中心。提供：ensureConnected() 确保连接可用（MCP/curl 双通道 + 多源凭证 + 缓存）、getIssue() 获取完整 ticket 上下文（含图片分析）、writeBack() 回写结果到 Jira。被 autopilot/hotfix/feature 调用，所有 Jira 相关逻辑集中在此。" --- # Jira 统一处理中心 ## 核心原则 **Jira 处理逻辑只在一处。** autopilot/hotfix/feature 不编写任何 Jira 处理代码，统一调用本 skill。 **双通道保障：MCP 优先，curl 兜底。** 当 MCP server 不可用时，自动检测多种凭证来源切换到 curl REST API 模式。 **连接缓存：同一 session 内只检测一次。** 首次检测结果存入 `state/jira-context.json`，5 分钟内复用。 ### Iron Law：四层检测不可跳过 **禁止在第 1 层 MCP 失败后直接降级为"未配置"。** 必须严格按顺序执行全部四层： 1. **缓存** → 5 分钟内有效结果直接复用 2. **MCP 工具** → 用 `jira_get_all_projects` 轻量探测 3. **多源凭证 curl** → 环境变量 → `~/.claude/mcp.json` → 项目 `.env` 4. 全部失败 → 才可降级 **违反此规则（跳过第 3 层直接写 mcpConfigured: false）是 BUG。** --- ## 入口参数 调用时必须传入： | 参数 | 说明 | 示例 | |------|------|------| | `action` | 操作类型 | `get_issue` / `write_back` | | `url` | Jira Issue URL（get_issue 时） | `https://xxx.atlassian.net/browse/PROJ-123` | | `mode` | 来源模式（autopilot/hotfix） | `autopilot` | | `context` | 回写上下文（write_back 时） | 见 writeBack 说明 | --- ## 函数 1：ensureConnected() 确保 Jira 可用。**严格按四层顺序执行，禁止跳过任何一层。** **执行步骤（必须完整执行，不可省略）：** **Step 0 — 检查缓存：** ``` Read state/jira-context.json if (文件存在 AND 有 "connectionCache" 字段) { cache = jiraContext.connectionCache elapsed = (Date.now() - Date.parse(cache.timestamp)) / 1000 if (elapsed < 300) { // 5 分钟内缓存有效，直接复用 return cache.result // { ok, method, config } } } ``` **Step 1 — 尝试 MCP 工具（轻量探测）：** ``` try { // 用 jira_get_all_projects 做轻量连通性测试 // 这是一个合法的只读 API，不会在 Jira 产生错误日志 mcp__atlassian__jira_get_all_projects(include_archived: false) result = { ok: true, method: "mcp" } // 写入缓存 cacheConnection(result) return result } catch (e) { // MCP 不可用 → 不要降级，不要写 mcpConfigured:false，继续 Step 2 } ``` **Step 2 — 多源凭证检测 + curl 测试（⛔ 不可跳过）：** ``` credentials = null // ---- Source A：环境变量（MCP server 原生配置方式）---- jiraUrl = Bash: echo "${JIRA_URL:-}" username = Bash: echo "${JIRA_USERNAME:-}" token = Bash: echo "${JIRA_API_TOKEN:-}" if (jiraUrl 非空 && username 非空 && token 非空) { credentials = { jiraUrl: jiraUrl.trim(), username: username.trim(), token: token.trim(), confluenceUrl: Bash: echo "${CONFLUENCE_URL:-}", confluenceUsername: Bash: echo "${CONFLUENCE_USERNAME:-}" || username, confluenceToken: Bash: echo "${CONFLUENCE_API_TOKEN:-}" || token, source: "env" } } // ---- Source B：~/.claude/mcp.json（现有逻辑）---- if (!credentials) { try { configRaw = Read("~/.claude/mcp.json") config = JSON.parse(configRaw) atlassian = config.mcpServers?.atlassian if (atlassian?.env?.JIRA_URL && atlassian?.env?.JIRA_USERNAME && atlassian?.env?.JIRA_API_TOKEN) { credentials = { jiraUrl: atlassian.env.JIRA_URL, username: atlassian.env.JIRA_USERNAME, token: atlassian.env.JIRA_API_TOKEN, confluenceUrl: atlassian.env.CONFLUENCE_URL || "", confluenceUsername: atlassian.env.CONFLUENCE_USERNAME || atlassian.env.JIRA_USERNAME, confluenceToken: atlassian.env.CONFLUENCE_API_TOKEN || atlassian.env.JIRA_API_TOKEN, source: "mcp.json" } } } catch (e) { // 文件不存在或解析失败，继续下一个 source } } // ---- Source C：项目根目录 .env 文件 ---- if (!credentials) { try { envContent = Read(".env") // 解析 JIRA_URL=xxx、JIRA_USERNAME=xxx、JIRA_API_TOKEN=xxx jiraUrl = envContent.match(/^JIRA_URL=(.+)$/m)?.[1]?.trim() username = envContent.match(/^JIRA_USERNAME=(.+)$/m)?.[1]?.trim() token = envContent.match(/^JIRA_API_TOKEN=(.+)$/m)?.[1]?.trim() if (jiraUrl && username && token) { credentials = { jiraUrl, username, token, confluenceUrl: envContent.match(/^CONFLUENCE_URL=(.+)$/m)?.[1]?.trim() || "", confluenceUsername: envContent.match(/^CONFLUENCE_USERNAME=(.+)$/m)?.[1]?.trim() || username, confluenceToken: envContent.match(/^CONFLUENCE_API_TOKEN=(.+)$/m)?.[1]?.trim() || token, source: ".env" } } } catch (e) { // .env 不存在，继续 } } // ---- curl 连通性测试 ---- if (credentials) { testResult = Bash: curl -sf -u "${credentials.username}:${credentials.token}" \ "${credentials.jiraUrl}/rest/api/3/myself" -o /dev/null -w "%{http_code}" --max-time 10 if (testResult == "200") { result = { ok: true, method: "curl", config: credentials } cacheConnection(result) return result } // curl 返回非 200 → 告知用户 HTTP 状态码和凭证来源 // 401 = Token 过期或无效 // 403 = 权限不足 // 其他 = 网络问题或 URL 错误 告知用户：「curl 测试失败（HTTP ${testResult}），凭证来源：${credentials.source}」 } ``` **Step 3 — 仅当全部失败时，交互式引导配置：** ``` // ⛔ 不要静默降级！用户给了 Jira URL，期望获取内容。必须明确告知并提供选择。 告知用户（AskUserQuestion）： "Jira 连接未配置。检测到你提供了 Jira URL，但当前无法访问 Jira API。 配置方式（推荐程度从高到低）： **A. claude.ai Atlassian 集成（推荐，最简单）** 在 Claude Code 设置中启用 Atlassian MCP 集成，OAuth 授权后自动可用。 路径：Claude Code → Settings → Integrations → Atlassian → Connect **B. 手动配置 API Token** 1. 访问 https://id.atlassian.com/manage-profile/security/api-tokens 生成 token 2. 选择以下任一方式存储： - 环境变量：export JIRA_URL=https://xxx.atlassian.net JIRA_USERNAME=you@email.com JIRA_API_TOKEN=xxx - ~/.claude/mcp.json：在 mcpServers.atlassian.env 下配置 - 项目 .env 文件：添加 JIRA_URL / JIRA_USERNAME / JIRA_API_TOKEN **C. 跳过 Jira，手动描述问题** 使用 URL 作为参考，手动描述问题内容。" 选项： A: "我去配置 Atlassian 集成" → 告知用户配置后重新运行 /hotfix，return { ok: false, action: "setup" } B: "我来配置 API Token" → 告知具体步骤，等待用户配置后重试 ensureConnected() C: "跳过，手动描述" → return { ok: false, configured: false, userSkipped: true } ``` **缓存写入辅助函数：** ``` function cacheConnection(result) { // 读取现有 jira-context.json（如有），合并缓存字段 existing = Read("state/jira-context.json") 或 {} existing.connectionCache = { timestamp: new Date().toISOString(), result: result } Write state/jira-context.json: existing } ``` --- ## 函数 2：getIssue(url, mode) 获取 Jira ticket 完整上下文，返回 `requirement` 和 `context`。 **参数：** - `url`: Jira Issue URL - `mode`: `autopilot` 或 `hotfix` **处理流程：** ``` 1. 解析 URL 提取 issueKey url matches /atlassian\.net\/browse\/([A-Z]+-\d+)/ issueKey = 匹配到的 key（如 PROJ-123） 2. 确保连接可用（调用 ensureConnected） conn = ensureConnected() if (!conn.ok) → 进入异常处理（见底部） 3. 获取 ticket（按 method 分支，增强字段） // ==================== MCP 路径 ==================== if (conn.method == "mcp") { issue = mcp__atlassian__jira_get_issue( issue_key: issueKey, fields: "summary,description,status,priority,labels,components,assignee,reporter,attachment,issuelinks,subtasks", comment_limit: 5 ) } // ==================== curl 路径 ==================== if (conn.method == "curl") { issueJson = Bash: curl -sf -u "${conn.config.username}:${conn.config.token}" \ "${conn.config.jiraUrl}/rest/api/3/issue/${issueKey}?fields=summary,description,status,priority,labels,components,assignee,reporter,attachment,issuelinks,subtasks,comment" \ -H "Accept: application/json" --max-time 30 issue = JSON.parse(issueJson) } 4. 提取需求文本 summary = issue.fields.summary descriptionText = extractTextFromADF(issue.fields.description) requirement = summary + "\n\n" + descriptionText 5. 提取丰富上下文 issueContext = { status: issue.fields.status?.name || "Unknown", priority: issue.fields.priority?.name || "Medium", labels: issue.fields.labels || [], components: (issue.fields.components || []).map(c => c.name), assignee: issue.fields.assignee?.displayName || "Unassigned", reporter: issue.fields.reporter?.displayName || "Unknown", linkedIssues: (issue.fields.issuelinks || []).map(link => { inward = link.inwardIssue outward = link.outwardIssue if (inward) return inward.key + " (" + link.type.inward + ")" if (outward) return outward.key + " (" + link.type.outward + ")" return null }).filter(Boolean), subtasks: (issue.fields.subtasks || []).map(s => s.key + ": " + s.fields?.summary), recentComments: [] } // 提取最近 5 条评论 if (conn.method == "mcp") { // MCP get_issue 已通过 comment_limit 返回评论 comments = issue.fields?.comment?.comments || [] issueContext.recentComments = comments.slice(-5).map(c => c.author?.displayName + ": " + extractTextFromADF(c.body) ) } if (conn.method == "curl") { comments = issue.fields?.comment?.comments || [] issueContext.recentComments = comments.slice(-5).map(c => { author = c.author?.displayName || "Unknown" body = extractTextFromADF(c.body) return author + ": " + body }) } // 将上下文附加到 requirement contextSummary = "" if (issueContext.status) contextSummary += "\n状态: " + issueContext.status if (issueContext.priority) contextSummary += "\n优先级: " + issueContext.priority if (issueContext.labels.length > 0) contextSummary += "\n标签: " + issueContext.labels.join(", ") if (issueContext.components.length > 0) contextSummary += "\n组件: " + issueContext.components.join(", ") if (issueContext.assignee) contextSummary += "\n经办人: " + issueContext.assignee if (issueContext.linkedIssues.length > 0) contextSummary += "\n关联: " + issueContext.linkedIssues.join(", ") if (issueContext.subtasks.length > 0) contextSummary += "\n子任务: " + issueContext.subtasks.join("; ") if (issueContext.recentComments.length > 0) { contextSummary += "\n\n[最近评论]\n" + issueContext.recentComments.join("\n---\n") } requirement += "\n\n[Issue 上下文]" + contextSummary 6. 获取开发信息（MCP 专属，可选增强） if (conn.method == "mcp") { try { devInfo = mcp__atlassian__jira_get_issue_development_info(issue_key: issueKey) if (devInfo.pullRequests?.length > 0 || devInfo.branches?.length > 0) { devSummary = "" if (devInfo.pullRequests?.length > 0) { devSummary += "\nPR: " + devInfo.pullRequests.map(pr => pr.name + " [" + pr.status + "]" ).join(", ") } if (devInfo.branches?.length > 0) { devSummary += "\n分支: " + devInfo.branches.map(b => b.name).join(", ") } requirement += "\n\n[开发信息]" + devSummary issueContext.pullRequests = devInfo.pullRequests || [] issueContext.branches = devInfo.branches || [] } } catch (e) { // 开发信息获取失败不阻塞主流程（可能无 DevTools 集成） } } 7. 分析图片附件 attachmentAnalysis = [] // ==================== MCP 路径 ==================== if (conn.method == "mcp") { 7a-mcp. 优先使用 jira_get_issue_images（专为图片分析设计） try { imageResult = mcp__atlassian__jira_get_issue_images(issue_key: issueKey) // 该工具只返回图片类附件的 inline ImageContent // >50MB 的图片自动跳过 // Claude 可直接进行多模态视觉分析 analysis = 对返回的每张图片描述：UI 问题位置、错误信息、设计标注、异常表现 attachmentAnalysis.push("[Jira Images]: " + analysis) } catch (e) { // jira_get_issue_images 失败 → 降级到 jira_download_attachments try { result = mcp__atlassian__jira_download_attachments(issue_key: issueKey) analysis = 对 result 中每张图片描述：UI 问题位置、错误信息、设计标注 attachmentAnalysis.push("[Jira Attachments]: " + analysis) } catch (e2) { attachmentAnalysis.push("[Jira Images]: 图片无法加载") } } 7b-mcp. Confluence Wiki 图片宏（从 ADF description 中提取） // 从 ADF 中提取 mediaSingle/mediaInline 节点的引用 inlineMediaRefs = extractMediaRefsFromADF(issue.fields.description) // 从 description 纯文本中提取 Confluence 附件 URL 模式 confluenceImageUrls = descriptionText.match( /\/wiki\/.*?\/attachments\/\d+\/[^?\s|!]+\.(?:png|jpg|jpeg|gif|webp)/gi ) || [] if (confluenceImageUrls.length > 0) { for each imgUrl in confluenceImageUrls (最多 3 张): try { pageId = imgUrl.match(/attachments\/(\d+)\//)?.[1] filename = decodeURIComponent(imgUrl.match(/attachments\/\d+\/([^?\s|]+)/)?.[1] || "") if (pageId && filename) { attList = mcp__atlassian__confluence_get_attachments(content_id: pageId, filename: filename) attId = attList.attachments?.[0]?.id if (attId) { mcp__atlassian__confluence_download_attachment(attachment_id: attId) analysis = 描述图片内容 attachmentAnalysis.push("[Confluence Image " + filename + "]: " + analysis) } } } catch (e) { attachmentAnalysis.push("[Confluence Image]: 图片无法加载，URL: " + imgUrl) } } } // ==================== curl 路径 ==================== if (conn.method == "curl") { 7a-curl. Jira 直接附件 attachments = issue.fields.attachment || [] imageAttachments = attachments.filter(a => /\.(png|jpg|jpeg|gif|webp)$/i.test(a.filename) ) for each att in imageAttachments (最多 5 张): // 文件大小检查（避免下载超大图片） if (att.size && att.size > 10 * 1024 * 1024) { attachmentAnalysis.push( "[" + att.filename + "]: 跳过，文件大小 " + (att.size / 1024 / 1024).toFixed(1) + "MB 超过 10MB 限制" ) continue } try { tmpPath = "/tmp/jira_att_${att.id}_${att.filename}" Bash: curl -sf -u "${conn.config.username}:${conn.config.token}" \ -o "${tmpPath}" "${att.content}" --max-time 30 // Read 工具支持读取图片（Claude 多模态），直接视觉分析 Read(tmpPath) analysis = 描述图片：UI 问题位置、错误信息、设计标注 attachmentAnalysis.push("[Jira Attachment " + att.filename + "]: " + analysis) // 清理临时文件 Bash: rm -f "${tmpPath}" } catch (e) { attachmentAnalysis.push("[Jira Attachment " + att.filename + "]: 下载失败") } 7b-curl. Confluence Wiki 图片宏 confluenceImageUrls = descriptionText.match( /\/wiki\/.*?\/attachments\/\d+\/[^?\s|!]+\.(?:png|jpg|jpeg|gif|webp)/gi ) || [] if (confluenceImageUrls.length > 0 && conn.config.confluenceUrl) { for each imgUrl in confluenceImageUrls (最多 3 张): try { filename = imgUrl.match(/attachments\/\d+\/([^?\s|]+)/)?.[1] || "unknown.png" filename = decodeURIComponent(filename) tmpPath = "/tmp/jira_conf_${filename}" // Confluence 附件 URL 需要加上 base URL fullUrl = conn.config.confluenceUrl.replace(/\/wiki\/?$/, "") + imgUrl Bash: curl -sf -u "${conn.config.confluenceUsername}:${conn.config.confluenceToken}" \ -o "${tmpPath}" "${fullUrl}" --max-time 30 Read(tmpPath) analysis = 描述图片内容 attachmentAnalysis.push("[Confluence Image " + filename + "]: " + analysis) Bash: rm -f "${tmpPath}" } catch (e) { attachmentAnalysis.push("[Confluence Image]: 图片无法加载，URL: " + imgUrl) } } } if (attachmentAnalysis.length > 0) { requirement += "\n\n[Jira 附件图片分析]\n" + attachmentAnalysis.join("\n") } 8. 保存上下文（供 DONE 阶段回写） Write state/jira-context.json: { "issueKey": issueKey, "issueUrl": url, "mode": mode, "method": conn.method, // "mcp" 或 "curl" "mcpConfigured": true, "curlConfig": conn.method == "curl" ? conn.config : null, "connectionCache": { "timestamp": new Date().toISOString(), "result": { ok: true, method: conn.method, config: conn.config || null } }, "issueContext": issueContext // 状态、优先级、标签、关联等 } 9. 返回 return { requirement: requirement, context: { issueKey, issueUrl: url, mode, method: conn.method, mcpConfigured: true } } ``` **ADF 文本提取（extractTextFromADF）— 增强版：** ``` // Atlassian Document Format → 结构化纯文本 // REST API v3 的 description 是 ADF JSON，不是纯字符串 function extractTextFromADF(adfNode) { if (!adfNode) return "" // 终端文本节点 if (adfNode.type == "text") return adfNode.text || "" // 换行和分隔 if (adfNode.type == "hardBreak") return "\n" if (adfNode.type == "rule") return "\n---\n" // 提及 if (adfNode.type == "mention") return "@" + (adfNode.attrs?.text || "") // 标题 if (adfNode.type == "heading") { level = adfNode.attrs?.level || 1 childText = (adfNode.content || []).map(c => extractTextFromADF(c)).join("") return "#".repeat(level) + " " + childText + "\n" } // 列表 if (adfNode.type == "bulletList" || adfNode.type == "orderedList") { return (adfNode.content || []).map((item, i) => { prefix = adfNode.type == "orderedList" ? (i + 1) + ". " : "- " return prefix + (item.content || []).map(c => extractTextFromADF(c)).join("") }).join("\n") + "\n" } // 代码块 if (adfNode.type == "codeBlock") { lang = adfNode.attrs?.language || "" code = (adfNode.content || []).map(c => extractTextFromADF(c)).join("") return "```" + lang + "\n" + code + "\n```\n" } // 表格 if (adfNode.type == "table") { rows = (adfNode.content || []).map(row => { cells = (row.content || []).map(cell => (cell.content || []).map(c => extractTextFromADF(c)).join("").trim() ) return "| " + cells.join(" | ") + " |" }) return rows.join("\n") + "\n" } // 内嵌媒体（图片等） if (adfNode.type == "mediaSingle" || adfNode.type == "mediaInline" || adfNode.type == "mediaGroup") { media = (adfNode.content || []).find(c => c.type == "media") if (media) { alt = media.attrs?.alt || media.attrs?.id || "image" return "[Media: " + alt + "]\n" } return "" } // 段落（加换行分隔） if (adfNode.type == "paragraph") { text = (adfNode.content || []).map(c => extractTextFromADF(c)).join("") return text + "\n" } // 通用递归 if (adfNode.content && Array.isArray(adfNode.content)) { return adfNode.content.map(child => extractTextFromADF(child)).join("") } return "" } ``` **curl 路径的 ADF 提取（用 Bash + jq）：** ```bash // 增强版 jq 表达式，支持更多 ADF 节点类型 echo '${issueJson}' | jq -r ' def extract: if .type == "text" then (.text // "") elif .type == "hardBreak" then "\n" elif .type == "mention" then ("@" + (.attrs.text // "")) elif .type == "heading" then (("#" * (.attrs.level // 1)) + " " + ([.content[]? | extract] | join("")) + "\n") elif .type == "codeBlock" then ("```" + (.attrs.language // "") + "\n" + ([.content[]? | extract] | join("")) + "\n```\n") elif .type == "bulletList" then ([.content[]? | "- " + ([.content[]? | extract] | join(""))] | join("\n")) + "\n" elif .type == "orderedList" then ([.content[]? | [.content[]? | extract] | join("") | "- " + .] | join("\n")) + "\n" elif .type == "table" then ([.content[]? | "| " + ([.content[]? | [.content[]? | extract] | join("") ] | join(" | ")) + " |"] | join("\n")) + "\n" elif .type == "paragraph" then ([.content[]? | extract] | join("")) + "\n" elif .content then [.content[] | extract] | join("") else "" end; .fields.description | extract ' 2>/dev/null | head -500 // 如果 jq 失败（未安装），降级用简单 jq echo '${issueJson}' | jq -r ' [.fields.description | .. | select(.type? == "text") | .text] | join(" ") ' 2>/dev/null | head -200 // 如果 jq 完全不可用，最终降级用 grep echo '${issueJson}' | grep -oP '"text"\s*:\s*"[^"]*"' | sed 's/"text"\s*:\s*"//;s/"$//' | head -100 ``` **从 ADF 提取媒体引用（extractMediaRefsFromADF）：** ``` function extractMediaRefsFromADF(adfNode) { refs = [] if (!adfNode) return refs if (adfNode.type == "media") { refs.push({ id: adfNode.attrs?.id, type: adfNode.attrs?.type, // "file" 或 "external" collection: adfNode.attrs?.collection, width: adfNode.attrs?.width, height: adfNode.attrs?.height, alt: adfNode.attrs?.alt }) } if (adfNode.content && Array.isArray(adfNode.content)) { for (child of adfNode.content) { refs = refs.concat(extractMediaRefsFromADF(child)) } } return refs } ``` **异常处理：** ``` catch (e) { if (!conn.ok) { // ensureConnected() 已通过交互式引导让用户选择了处理方式 // 到这里说明用户选择了"跳过，手动描述" // ⛔ 不要静默降级。明确告知用户： 告知用户： "⚠️ 无法获取 Jira ticket 内容（${issueKey}）。 将使用 URL 作为参考，请手动描述问题： - 问题是什么？ - 在哪个页面/功能？ - 期望行为 vs 实际行为？" Write state/jira-context.json: { "issueKey": issueKey, "issueUrl": url, "mode": mode, "method": "none", "mcpConfigured": false } return { requirement: url, // 降级为原始 URL context: { issueKey, issueUrl: url, mode, method: "none", mcpConfigured: false } } } // 其他异常（图片下载失败等），不阻塞主流程 console.warn("部分数据获取失败，继续：" + e.message) } ``` --- ## 函数 3：writeBack(context) DONE 阶段回写结果到 Jira。 **参数：** ```json { "issueKey": "PROJ-123", "issueUrl": "https://xxx.atlassian.net/browse/PROJ-123", "mode": "autopilot", "changes": ["修复了登录按钮样式错位", "新增用户头像上传功能"], "testResult": "通过" } ``` **处理流程：** ``` 1. Read state/jira-context.json 验证 context 存在 if (文件不存在 OR mcpConfigured == false) { // 非 Jira 来源 或 连接不可用，跳过 return } method = jiraContext.method // "mcp" 或 "curl" // 如果缓存中有连接信息，直接使用，无需重新检测 if (method == "curl" && !jiraContext.curlConfig) { // 缓存丢失，重新检测 conn = ensureConnected() if (!conn.ok) { 告知用户回写失败; return } method = conn.method } 2. 收集修复元数据 fixer = "Claude " + (context.mode == "hotfix" ? "Hotfix" : "Autopilot") + " Agent" timestamp = Bash: date "+%Y-%m-%d %H:%M:%S %Z" 3. 构建回写 comment comment = """ ✅ ${fixer} 已完成 **修复摘要**： ${context.changes.map(c => "- " + c).join('\n')} **测试结果**：${context.testResult} **时间**：${timestamp} **执行人**：${fixer} """ 4. 回写到 Jira // ==================== MCP 路径 ==================== if (method == "mcp") { try { mcp__atlassian__jira_add_comment(issue_key: context.issueKey, body: comment) } catch (e) { 告知用户：「评论添加失败：${e.message}」 } } // ==================== curl 路径 ==================== if (method == "curl") { curlConfig = jiraContext.curlConfig // 构建 ADF 格式的 comment body // 将 markdown comment 转换为 ADF 段落 adfParagraphs = comment.split('\n').filter(Boolean).map(line => ({ "type": "paragraph", "content": [{ "type": "text", "text": line }] })) commentBody = { "body": { "type": "doc", "version": 1, "content": adfParagraphs } } result = Bash: curl -sf -u "${curlConfig.username}:${curlConfig.token}" \ -X POST "${curlConfig.jiraUrl}/rest/api/3/issue/${context.issueKey}/comment" \ -H "Content-Type: application/json" \ -d '${JSON.stringify(commentBody)}' \ -w "\n%{http_code}" --max-time 15 httpCode = result 最后一行 if (httpCode != "201" && httpCode != "200") { 告知用户：「评论添加失败（HTTP ${httpCode}）」 } } 5. 推进状态（选最接近「完成/提测」的状态） // ==================== MCP 路径 ==================== if (method == "mcp") { try { transitions = mcp__atlassian__jira_get_transitions(issue_key: context.issueKey) // 优先匹配顺序（中英文）： targetNames = ["Done", "完成", "已完成", "Fixed", "已修复", "提测", "Ready for QA", "In Review", "Resolved", "已解決"] target = transitions.find(t => targetNames.includes(t.name)) if (target) { mcp__atlassian__jira_transition_issue(issue_key: context.issueKey, transition_id: target.id) } else { 告知用户：「未找到匹配的完成状态，已添加评论，请手动转移。」 } } catch (e) { 告知用户：「状态转移失败：${e.message}。已添加评论。」 } } // ==================== curl 路径 ==================== if (method == "curl") { curlConfig = jiraContext.curlConfig // 获取可用 transitions transitionsJson = Bash: curl -sf -u "${curlConfig.username}:${curlConfig.token}" \ "${curlConfig.jiraUrl}/rest/api/3/issue/${context.issueKey}/transitions" \ -H "Accept: application/json" --max-time 10 if (transitionsJson 非空) { transitions = JSON.parse(transitionsJson).transitions || [] targetNames = ["Done", "完成", "已完成", "Fixed", "已修复", "提测", "Ready for QA", "In Review", "Resolved", "已解決"] target = transitions.find(t => targetNames.some(n => t.name === n)) if (target) { Bash: curl -sf -u "${curlConfig.username}:${curlConfig.token}" \ -X POST "${curlConfig.jiraUrl}/rest/api/3/issue/${context.issueKey}/transitions" \ -H "Content-Type: application/json" \ -d '{"transition":{"id":"${target.id}"}}' --max-time 10 } else { 告知用户：「未找到匹配的完成状态（可用: ${transitions.map(t => t.name).join(', ')}），已添加评论，请手动转移。」 } } } ``` --- ## 调用示例 **autopilot / hotfix / feature 中获取 issue：** ``` if (requirement matches /atlassian\.net\/browse\/([A-Z]+-\d+)/) { result = Skill: jira-mcp-setup ( action: "get_issue", url: requirement, mode: "autopilot" // 或 "hotfix" ) requirement = result.requirement // jira-context.json 已由 skill 写入 } ``` **DONE 阶段回写：** ``` if (state/jira-context.json 存在) { Skill: jira-mcp-setup ( action: "write_back", context: { issueKey: "...", issueUrl: "...", mode: "...", changes: [...], testResult: "..." } ) } ``` --- ## 故障排除 | 问题 | 解决方案 | |------|----------| | MCP 工具不可用 + 环境变量有配置 | 自动切换 curl 模式（Source A） | | MCP 工具不可用 + `~/.claude/mcp.json` 有配置 | 自动切换 curl 模式（Source B） | | MCP 工具不可用 + `.env` 有配置 | 自动切换 curl 模式（Source C） | | MCP 工具不可用 + 无任何凭证 | 引导用户配置（三种方式任选） | | curl 测试返回 401 | API Token 过期或无效，提示用户更新对应来源的凭证 | | curl 测试返回 403 | 权限不足，确认账号有访问 Jira 项目权限 | | curl 测试返回非 200 | 显示 HTTP 状态码和凭证来源，提示检查 URL 和网络 | | `jira_get_issue_images` 返回空 | issue 无图片附件，或附件为非图片类型（正常情况） | | `jira_get_issue_images` 失败 | 自动降级到 `jira_download_attachments` | | curl 下载附件 >10MB | 自动跳过该图片，告知文件大小 | | curl 下载附件超时 | 单张图片 `--max-time 30`，超时跳过该图 | | ADF 描述解析失败 | 三级降级：增强 jq → 简单 jq → grep | | Confluence 图片下载失败 | 检查 Confluence token 是否有访问权限 | | Jira 状态转移无匹配 | 列出所有可用状态名，只添加评论，提示手动转移 | | 回写失败 | 显示 HTTP 状态码，记录警告，不阻塞流程完成 | | `jira_download_attachments` 无输出 | 该工具只返回文件类附件；issue 无附件则返回空摘要 | | 子 Agent 中环境变量不可用 | 自动尝试 Source B / C 作为兜底 | | 连接缓存过期 | 超过 5 分钟自动重新检测 |