Jira集成引擎(免费版)

Jira问题跟踪与项目管理集成引擎，通过REST API操作Jira实例，覆盖问题管理、Sprint规划与工作流自动化。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="your_api_key_here"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。

核心能力

1. 问题管理

通过Jira REST API v3管理问题：

# 创建问题
curl -X POST "https://your-domain.atlassian.net/rest/api/3/issue" 
  -u "email@example.com:API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "fields": {
      "project": {"key": "PROJ"},
      "summary": "实现用户登录功能",
      "description": {"type": "doc","version": 1,"content": [{"type": "paragraph","content": [{"type": "text","text": "需要实现OAuth登录"}]}]},
      "issuetype": {"name": "Story"},
      "priority": {"name": "High"},
      "assignee": {"accountId": "user-account-id"}
    }
  }'

# 查询问题
curl -X GET "https://your-domain.atlassian.net/rest/api/3/issue/PROJ-123" 
  -u "email@example.com:API_TOKEN"

# 更新问题
curl -X PUT "https://your-domain.atlassian.net/rest/api/3/issue/PROJ-123" 
  -u "email@example.com:API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"fields": {"summary": "更新后的标题"}}'

处理: 按照skill规范执行问题管理操作,遵循单一意图原则。

2. JQL高级查询

# JQL查询
curl -X GET "https://your-domain.atlassian.net/rest/api/3/search" 
  -u "email@example.com:API_TOKEN" 
  --data-urlencode 'jql=project = PROJ AND sprint in openSprints() AND status != Done ORDER BY priority DESC' 
  -G

常用JQL模式：

• 当前Sprint未完成：sprint in openSprints() AND status != Done
• 某人待办：assignee = "user@domain.com" AND statusCategory != Done
• 高优先级缺陷：issuetype = Bug AND priority in (Highest, High) AND status = Open
• 过期问题：duedate < now() AND statusCategory != Done

处理: 按照skill规范执行JQL高级查询操作,遵循单一意图原则。 输出: 返回JQL高级查询的执行结果,包含操作状态和输出数据。

3. Sprint与看板管理

# 获取活跃Sprint
curl -X GET "https://your-domain.atlassian.net/rest/agile/1.0/board/1/sprint?state=active" 
  -u "email@example.com:API_TOKEN"

# 将问题移入Sprint
curl -X POST "https://your-domain.atlassian.net/rest/agile/1.0/sprint/1/issue" 
  -u "email@example.com:API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"issues": ["PROJ-1", "PROJ-2"]}'

# 创建Sprint
curl -X POST "https://your-domain.atlassian.net/rest/agile/1.0/sprint" 
  -u "email@example.com:API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"name": "Sprint 15", "startDate": "2026-08-01", "endDate": "2026-08-14", "originBoardId": 1}'

输入: 用户提供Sprint与看板管理所需的指令和必要参数。 处理: 按照skill规范执行Sprint与看板管理操作,遵循单一意图原则。

• 执行Sprint与看板管理操作,处理输入数据并返回结果
• 验证执行结果,确认输出符合预期格式
• 异常时参考错误处理章节进行恢复
• 关键参数: sprint与看板管理 选项

4. 工作流与状态流转

# 获取可用状态流转
curl -X GET "https://your-domain.atlassian.net/rest/api/3/issue/PROJ-123/transitions" 
  -u "email@example.com:API_TOKEN"

# 执行状态流转
curl -X POST "https://your-domain.atlassian.net/rest/api/3/issue/PROJ-123/transitions" 
  -u "email@example.com:API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"transition": {"id": "21"}}'

# 添加评论
curl -X POST "https://your-domain.atlassian.net/rest/api/3/issue/PROJ-123/comment" 
  -u "email@example.com:API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"body": {"type": "doc","version": 1,"content": [{"type": "paragraph","content": [{"type": "text","text": "已修复，请验证"}]}]}}'

输入: 用户提供工作流与状态流转所需的指令和必要参数。 输出: 返回工作流与状态流转的执行结果,包含操作状态和输出数据。

• 执行工作流与状态流转操作,处理输入数据并返回结果
• 验证执行结果,确认输出符合预期格式
• 异常时参考错误处理章节进行恢复
• 关键参数: 工作流与状态流转 选项

能力覆盖范围

本skill还覆盖以下能力场景: 问题跟踪、项目看板与工作流、自动化、免费版、问题跟踪与项目管、理集成引擎、覆盖问题管理、看板操作与工作流、核心能力、批量操作、看板配置、高级查询与筛选器。这些能力在上述核心功能中均有对应处理逻辑。

适用场景

不适用于：Jira插件开发、Jira管理员配置、Jira Server/Data Center安装部署。

使用流程

1. 配置认证（邮箱+API Token）
2. 确定Jira实例URL和项目Key
3. 选择操作类型（创建/查询/更新/流转）
4. 构造并发送REST API请求
5. 解析响应并格式化输出

命令参数说明

• --data-urlencode: 命令参数,用于指定操作选项
• -account-id: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项
• -G: 命令参数,用于指定操作选项
• -X: 命令参数,用于指定操作选项

命令参数说明

• -Type: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项
• -G: 命令参数,用于指定操作选项
• -X: 命令参数,用于指定操作选项

命令参数说明

• -X: 命令参数,用于指定操作选项
• -G: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项

命令参数说明

• -G: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项
• -X: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项

命令参数说明

• -Type: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项
• -G: 命令参数,用于指定操作选项
• -X: 命令参数,用于指定操作选项

命令参数说明

• -X: 命令参数,用于指定操作选项
• -G: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项

命令参数说明

• -G: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项
• -X: 命令参数,用于指定操作选项

命令参数说明

• -G: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项
• -X: 命令参数,用于指定操作选项

命令参数说明

• -H: 命令参数,用于指定操作选项
• -X: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项
• -G: 命令参数,用于指定操作选项

示例

示例1：查询当前Sprint问题

curl -s -X GET "https://your-domain.atlassian.net/rest/api/3/search" 
  -u "email@example.com:API_TOKEN" 
  --data-urlencode 'jql=project = PROJ AND sprint in openSprints() ORDER BY priority DESC' 
  -G | jq '.issues[] | {key: .key, summary: .fields.summary, status: .fields.status.name, assignee: .fields.assignee.displayName}'

输出：当前Sprint所有问题的Key、标题、状态和负责人列表。

错误处理

常见问题

Q1: 如何获取Jira API Token？

登录Atlassian账户（https://id.atlassian.com/manage-profile/security/api-tokens），点击"Create API token"，输入标签名后复制Token。使用时配合注册邮箱：-u "your-email@domain.com:YOUR_API_TOKEN"。注意Token只显示一次，需妥善保存。Server/Data Center版本使用用户名+密码或Personal Access Token（PAT）。

Q2: Jira Cloud和Server/Data Center的API有什么区别？

Cloud使用https://your-domain.atlassian.net/rest/api/3/，认证用邮箱+API Token。Server/DC使用https://your-jira-server/rest/api/2/，认证用用户名+密码或PAT。API v3支持Atlassian Document Format（ADF）富文本，v2使用纯文本。如果不需要富文本，v2的API在Cloud上仍可用，但建议迁移到v3。部分敏捷API路径Cloud为/rest/agile/1.0/，Server一致。

Q3: JQL查询结果如何分页？

默认返回50条，最多100条。使用startAt和maxResults参数分页：?jql=...&startAt=0&maxResults=100。遍历所有结果时，循环请求直到total <= startAt + maxResults。大批量查询建议使用fields参数限制返回字段减少响应体积：&fields=key,summary,status,assignee。导出全量数据可考虑Jira的CSV导出功能或/rest/api/3/search的expand参数。

已知限制

• 需要Jira实例的网络访问权限
• API Token权限受账户角色限制
• API速率限制：Cloud每分钟每用户约40请求

升级提示

本免费版提供基础功能。升级到完整版 jira 获取全部能力和高级特性。