🎫 jira-ticket — Jira 票务 — 使用网络研究内容创建 Jira 票

创建内容由网络搜索丰富的 Jira 工单。按顺序遵循以下阶段。

设置

需要三个环境变量：

• JIRA_BASE_URL — 你的 Atlassian 实例（例如 https://yourteam.atlassian.net）
• JIRA_EMAIL — 与你的 Atlassian 账户关联的邮箱
• JIRA_API_TOKEN — 来自 https://id.atlassian.com/manage-profile/security/api-tokens 的 API 令牌

所有 Jira API 调用通过 curl -u 使用基本认证并强制使用 HTTP/1.1：

curl --http1.1 -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" -H "Content-Type: application/json" "$JIRA_BASE_URL/rest/api/3/..."

阶段 1 — 解析参数

解析用户请求，提取以下字段：

阶段 2 — 网络研究（如适用）

如果用户要求研究，或者工单可以从上下文受益（例如，引用外部 API 的缺陷报告，关于集成第三方服务的故事）：

• 使用 web_search 工具搜索相关主题。
• 使用 xurl 工具或 curl 获取关键页面以获取详情。
• 提取最相关信息：错误描述、API 文档、最佳实践、版本说明或解决方案方法。

将发现编译成结构化摘要：

### 研究摘要
来源: [URL]
关键发现: ...
相关细节: ...

如果不需要研究，跳过阶段 3。

阶段 3 — 编写工单内容

使用 Atlassian 文档格式（ADF）构建工单描述。结合：

• 用户的原始请求/上下文
• 阶段 2 的研究发现（如有）
• 验收标准（创建 Story 时）
• 重现步骤（创建 Bug 时）

保持描述简洁且可操作。

ADF 结构

Jira API v3 对描述字段使用 ADF。最小示例：

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "描述文本。" }]
    }
  ]
}

更丰富的格式（标题、列表、链接）：

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 3 },
      "content": [{ "type": "text", "text": "摘要" }]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [{ "type": "text", "text": "项目一" }]
            }
          ]
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "来源: " },
        {
          "type": "text",
          "text": "链接文本",
          "marks": [{ "type": "link", "attrs": { "href": "https://example.com" } }]
        }
      ]
    }
  ]
}

阶段 4 — 验证项目和字段

在创建工单之前，验证项目存在并发现可用字段：

# 验证项目
curl --http1.1 -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" -H "Content-Type: application/json" \
  "$JIRA_BASE_URL/rest/api/3/project/$PROJECT_KEY" | jq '{key, name, id}'
# 列出项目的可用问题类型
curl --http1.1 -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" -H "Content-Type: application/json" \
  "$JIRA_BASE_URL/rest/api/3/project/$PROJECT_KEY/statuses" | jq '.[].name'

如果项目或问题类型无效，报告错误并请用户更正。

阶段 5 — 创建工单

curl --http1.1 -s -X POST \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_BASE_URL/rest/api/3/issue" \
  -d '{
    "fields": {
      "project": { "key": "PROJECT_KEY" },
      "summary": "工单摘要",
      "issuetype": { "name": "Task" },
      "priority": { "name": "Medium" },
      "description": { ADF对象 },
      "labels": ["标签1", "标签2"]
    }
  }'

提取响应：

# 解析响应的工单键和 URL
ISSUE_KEY=$(echo "$RESPONSE" | jq -r '.key')
ISSUE_URL="$JIRA_BASE_URL/browse/$ISSUE_KEY"

如果 API 返回错误，显示错误消息并建议更正。

阶段 6 — 报告

向用户呈现结果：

• 工单键: 例如 ENG-1234
• URL: 工单的直接链接
• 摘要: 设置的标题
• 包含研究: 是/否，并列出来源

注意事项

• Jira REST API v3 需要 ADF 格式的描述 — 纯文本或 markdown 将被拒绝。
• 速率限制：Jira Cloud 允许每个用户每分钟约 100 个请求。
• NemoClaw 中的 jira.yaml 网络策略预设已允许 *.atlassian.net、auth.atlassian.com 和 api.atlassian.com 在 443 端口。
• 要在 NemoClaw 的沙箱中使用此技能，请在沙箱策略中启用 Jira 预设。

示例

# 创建简单任务
/jira-ticket ENG "更新 API 速率限制文档"
# 创建带网络研究的缺陷
/jira-ticket ENG --type Bug --search "Node.js fetch timeout ECONNRESET" "修复支付服务中的间歇性 ECONNRESET"
# 创建带优先级和标签的故事
/jira-ticket PLATFORM --type Story --priority High --labels "q2,backend" "为移动客户端添加 OAuth2 PKCE 流程"