name: jira description: 用于问题管理和搜索的Jira Cloud集成技能。当处理Jira工单、使用JQL搜索问题、创建或更新问题、添加评论或转换问题状态时，应使用此技能。涵盖REST API v3和Jira查询语言。 author: Joseph OBrien status: unpublished updated: ‘2025-12-23’ version: 1.0.1 tag: skill type: skill

Jira集成技能

此技能通过REST API v3和JQL查询直接与Jira Cloud交互。

前提条件

设置以下环境变量（或在.env文件中设置）：

JIRA_DOMAIN=company.atlassian.net
JIRA_EMAIL=user@company.com
JIRA_API_TOKEN=your-api-token

在以下地址生成API令牌：https://id.atlassian.com/manage-profile/security/api-tokens

核心工作流

1. 获取问题详情

检索问题信息：

python scripts/jira_api.py GET /issue/PROJ-123

指定字段：

python scripts/jira_api.py GET "/issue/PROJ-123?fields=summary,status,assignee"

2. 使用JQL搜索

使用JQL搜索问题：

python scripts/jira_api.py GET /search --query "jql=project=AOP AND status='In Progress'&maxResults=20"

常见JQL模式 - 参见references/jql-reference.md：

我的未解决问题：assignee = currentUser() AND resolution = Unresolved
最近更新：updated >= -1d ORDER BY updated DESC
冲刺工作：sprint in openSprints() AND assignee = currentUser()

3. 创建问题

创建新问题，使用ADF格式描述（参见references/adf-format.md）：

python scripts/jira_api.py POST /issue --data '{
  "fields": {
    "project": { "key": "PROJ" },
    "issuetype": { "name": "Task" },
    "summary": "问题标题",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "此处为描述" }]
        }
      ]
    }
  }
}'

4. 更新问题

更新现有问题的字段：

python scripts/jira_api.py PUT /issue/PROJ-123 --data '{
  "fields": {
    "summary": "更新后的标题",
    "labels": ["label1", "label2"]
  }
}'

5. 添加评论

添加评论（需要ADF格式）：

python scripts/jira_api.py POST /issue/PROJ-123/comment --data '{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "此处为评论文本" }]
      }
    ]
  }
}'

6. 转换问题状态

首先，获取可用转换：

python scripts/jira_api.py GET /issue/PROJ-123/transitions

然后转换到新状态：

python scripts/jira_api.py POST /issue/PROJ-123/transitions --data '{
  "transition": { "id": "21" }
}'

7. 分配问题

分配问题：

# 首先获取用户账户ID
python scripts/jira_api.py GET "/user/search?query=username"

# 然后分配
python scripts/jira_api.py PUT /issue/PROJ-123/assignee --data '{
  "accountId": "user-account-id"
}'

取消分配：

python scripts/jira_api.py PUT /issue/PROJ-123/assignee --data '{"accountId": null}'

直接使用curl

无需辅助脚本的快速操作：

JIRA_DOMAIN="company.atlassian.net"
AUTH=$(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64)

curl -s "https://$JIRA_DOMAIN/rest/api/3/issue/PROJ-123" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json"

参考文件

references/api-endpoints.md - 完整的REST API v3端点参考
references/jql-reference.md - JQL运算符、函数、字段和模式
references/adf-format.md - Atlassian文档格式，用于富文本字段

常见模式

批量操作

高效获取多个问题：

python scripts/jira_api.py GET /search --query "jql=key in (PROJ-1,PROJ-2,PROJ-3)"

获取项目信息

列出项目或获取项目详情：

python scripts/jira_api.py GET /project
python scripts/jira_api.py GET /project/PROJ

获取可用问题类型

python scripts/jira_api.py GET "/project/PROJ?expand=issueTypes"

错误处理

常见错误代码：

400：错误请求 - 检查JSON语法和字段名称
401：未授权 - 验证凭据
403：禁止访问 - 检查用户权限
404：未找到 - 验证问题键是否存在
429：速率限制 - 等待并重试

对于字段验证错误，Jira会返回详细的错误消息，指示哪些字段无效。