create-jira-ticket

根据用户的指示，使用 Atlassian CLI（acli） 创建 JIRA 工单。如果能从分支名称中的 JIRA 键推断项目，优先使用与当前分支相同的项目；否则询问用户选择哪个项目。加载该项目的 Epic，为新工作推断最合适的 Epic，显示预览，并在创建问题前获得明确确认。

用法：

• /create-jira-ticket — 在同一条消息中通过 $ARGUMENTS 传入工单描述（摘要意图、Bug 或功能、验收标准、链接等）

说明：

1. 验证 acli 已安装并通过身份验证：

   • 运行 acli auth status。
   • 如果找不到该命令，显示以下错误并停止：

     Atlassian CLI (acli) is not installed.
     Install with: brew tap atlassian/acli && brew install acli
     

   • 如果身份验证失败，显示以下错误并停止：

     Atlassian CLI is not authenticated.
     Run: acli auth login
     

2. 确定 JIRA 项目键：

   • 运行 git branch --show-current。如果处于 detached HEAD 状态，注明这一点，但如果仍能选择项目，则继续。
   • 按照模式 [A-Z][A-Z0-9]+-[0-9]+（不区分大小写；统一转换为大写）在分支名称中匹配 JIRA 问题键。如果找到，将 - 前的前缀设为项目键（例如，PROJ-123 → PROJ）。
   • 如果未找到键，运行：

     acli jira project list --json
     

     使用 AskUserQuestion 让用户选择项目键。

3. 解析 $ARGUMENTS 中的指示：

   • 如果内容为空，使用 AskUserQuestion 收集要创建的工单内容，然后继续。
   • 尽可能推断以下内容：
     • 摘要（简短的祈使式标题）
     • 问题类型（Bug、Story、Task 等）——根据措辞判断（“fix”“broken” → Bug；“add”“implement” → Story/Task）
     • 描述 — 使用清晰的章节起草描述（Bug：问题所在、复现步骤、预期结果与实际结果；Story/Task：目标和验收标准）。你会将其转换为 JIRA 的 ADF（见下方 ADF 格式参考；JIRA 不会在描述字段中渲染 Markdown）。
     • 可选：优先级、标签、Figma URL（https://www.figma.com/...）
     • 如果用户指定了某个 Epic（例如 PROJ-100 这样的键或标题），将其视为第 5 步中的手动 Epic 偏好。

4. 列出项目中的 Epic：

   • 运行：

     acli jira workitem search --jql "project = <PROJECT-KEY> AND issuetype = Epic" --json --limit 50
     

     将 <PROJECT-KEY> 替换为实际的键。如果结果为空，仅当你的 Jira 版本要求时，才尝试将 issuetype = Epic 替换为 type = Epic；如果仍为空，则报告此项目中未找到 Epic。
   • 从 JSON 中收集每个 Epic 的键、摘要和状态（如果存在），以供显示。

5. 推荐 Epic：

   • 如果用户在第 3 步指定了手动 Epic，且该键存在于列表中（或通过 acli jira workitem view <KEY> --fields summary,issuetype --json 确认其类型为 Epic），则将其设为推荐 Epic。
   • 如果没有 Epic，将推荐 Epic设为无，并跳过匹配。
   • 否则，根据新工单的摘要 + 描述（关键词、产品领域、组件）与每个 Epic 的摘要（以及返回的描述）进行比较。选择主题匹配度最高的 Epic；如果匹配度相同，优先选择状态不是 Done/Closed 的 Epic。
   • 写出一句话理由（例如：“与 ‘Checkout’ Epic 匹配，因为该工作描述了支付流程。”）。

6. 确认预览（必需）：

   • 显示清晰的预览：
     • 项目、问题类型、摘要
     • 推荐的史诗（键 + 摘要 + 理由），或“无 — 项目中没有史诗”／“无 — 用户拒绝指定父级”
     • 简短的描述大纲或项目符号列表（预览中不必包含完整的 ADF）
     • Figma URL（如有）
   • 使用 AskUserQuestion，让用户可以：
     • 创建并使用推荐的史诗（创建子问题时将 parent 设置为该史诗键 — 见步骤 7）
     • 选择其他史诗（显示键 + 摘要）
     • 不使用史诗父级创建（省略 parent；仅在问题类型允许时 — 用户选择不指定时不要强行指定史诗）
     • 编辑 — 用户修改说明；返回步骤 3
     • 取消 — 停止
   • 在用户确认创建（上述任一“创建”选项）之前，不要调用 acli jira workitem create。

7. 使用 acli 创建工作项：

   • 根据整理后的内容构建 ADF description（包括标题、段落、项目符号列表、验收标准的任务列表）。遵循下方的 ADF 格式参考，或运行 acli jira workitem create --generate-json 并根据站点的架构调整。
   • 写入 JSON 文件并运行：

     acli jira workitem create --from-json <temp-file.json> --json
     

   • 包含 "project": "<PROJECT-KEY>"、"type": "<IssueType>"、"summary": "..." 和 "description": { ... ADF ... }。
   • 父级／史诗：如果用户确认了史诗，则包含 "parent": "<EPIC-KEY>"，除非问题类型是 Epic（除非用户明确要求，否则不要将 Epic 设为另一个 Epic 的子级）。如果 API 拒绝 parent（某些经典项目使用 Epic Link 自定义字段），请读取错误信息，检查适用于该项目的 --generate-json，然后使用正确的字段格式重试一次；如果仍然失败，告知用户在 Jira UI 中设置史诗，并在问题已创建但没有父级时报告创建的键后停止。
   • 成功后，输出新的 键以及 JSON 中提供的浏览 URL。

8. 附加 Figma 设计（如有提供）：

   • 如果说明中包含 Figma URL，请使用 Figma for Jira 的 Add Design 机制附加。
   • 设计以问题级实体属性的形式存储。请从已创建工单的 JSON 响应中获取站点 URL，然后：
     1. **确定 Figma 属性键：**列出问题的实体属性：

        curl -s -H "Authorization: Bearer $(acli auth token)" \
          "https://<site>.atlassian.net/rest/api/3/issue/<JIRA-ID>/properties/"
        

     2. **设置设计属性：**属性键和值的格式取决于 Figma for Jira 应用；通常如下：

        curl -s -X PUT -H "Authorization: Bearer $(acli auth token)" \
          -H "Content-Type: application/json" \
          "https://<site>.atlassian.net/rest/api/3/issue/<JIRA-ID>/properties/<figma-property-key>" \
          -d '{"figmaDesigns": [{"url": "<figma-url>", "name": "<design-name>"}]}'
        

   • 如果 REST 调用失败，请改为将 Figma URL 放入描述中，并告知用户可以手动使用 Add Design。

9. 边缘情况：

   • 必填自定义字段：如果创建因验证错误失败，请显示相关字段并询问用户提供值，然后重试。
   • 如果 issuetype = Epic 搜索没有结果，但项目使用了其他史诗类型名称，请尝试列出该项目的问题类型（acli／REST），并调整 JQL 重试一次。

**面向用户的摘要：**项目、新问题键、URL、使用的史诗（或无）以及 Figma 附加结果（或回退方式）。

---

ADF 格式参考

JIRA 不会渲染 Markdown。描述必须使用 Atlassian Document Format (ADF) ——一种基于 JSON 的文档格式。--description-file 标志会将文件内容视为纯文本，因此请使用 --from-json 来编写富文本描述。

重要提示： JSON 负载中的 description 字段必须是 ADF 对象，而不是字符串。运行 acli jira workitem create --generate-json，查看适用于你站点的预期架构。

常见的 ADF 节点类型：

Markdown	ADF type	说明
## Heading	带有 attrs.level 的 heading	级别为 1–6
纯文本	带有 text 子节点的 paragraph
**bold**	带有 marks: [{"type": "strong"}] 的 text
*italic*	带有 marks: [{"type": "em"}] 的 text
- item	bulletList > listItem > paragraph
1. item	orderedList > listItem > paragraph
- [ ] task	taskList > taskItem（状态：TODO/DONE）
`code`	带有 marks: [{"type": "code"}] 的 text	行内代码
代码块	带有 attrs.language 的 codeBlock
---	rule	水平分隔线
[link](url)	带有 marks: [{"type": "link", "attrs": {"href": "url"}}] 的 text

ADF 描述示例：

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Description" }]
    },
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "What needs to be done and why." }]
    },
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Acceptance Criteria" }]
    },
    {
      "type": "taskList",
      "attrs": { "localId": "ac-list" },
      "content": [
        {
          "type": "taskItem",
          "attrs": { "localId": "ac-1", "state": "TODO" },
          "content": [{ "type": "text", "text": "First criterion" }]
        },
        {
          "type": "taskItem",
          "attrs": { "localId": "ac-2", "state": "TODO" },
          "content": [{ "type": "text", "text": "Second criterion" }]
        }
      ]
    }
  ]
}